feat(ui): Add machine library for authoring flows#8919
Merged
Conversation
- Tighten Actor.send and Actor.can to accept TEvent only, removing the AnyEventObject escape hatch that silently swallowed typos - Add context init option to CreateActorOptions so runtime dependencies can be injected at actor-creation time without module-level closures - Add types.test-d.ts with @ts-expect-error guards and expectTypeOf assertions covering send/can rejection, snapshot types, and assign - Extract delete-organization-machine and leave-organization-machine as module-level factories; migrate both sections to useMachine with the split-component pattern (loader + ready) so the machine is always instantiated with a non-null organization/membership
…mounts In StrictMode (on by default in Next.js dev), React runs effects twice: start → stop → start. The second start() hit the `if (started) return` guard and bailed out, leaving status = 'stopped'. Every subsequent send() then short-circuited, so dialogs driven by useMachine never opened. Fix: stop() resets `started = false` to allow a clean restart, and start() sets status = 'active' before entering state so a restart-after-stop works.
…-fire After stop() + start() (StrictMode, Suspense remount), the actor was re-entering whatever state it was stopped in. If that state had an invoke (e.g. deleting), the async function would fire a second time. Fix: start() now resets context and value to their initial values before entering state, so a restart always begins from idle rather than continuing a half-completed flow. Adds a regression test for the double-invoke case.
…factories useMachine creates the actor once, so any function passed inline to the machine factory is captured from the first render only. If membership or organization changed under the same mount, the old .destroy() would fire. Fix: pin a ref to the prop on every render; the machine receives a stable wrapper that reads from the ref at call time. Adds a regression test that re-renders with a fresh destroy prop before triggering the flow and asserts the fresh function is invoked.
…Effect Replaces the ref-wrapper workaround in section components with the XState pattern: actor.setContext() silently patches context each render so invoke sources always call the latest prop-derived function without stale closures. Section machine factories are now module-level singletons; the destroy/leave function is injected via useMachine options.context instead of a closure.
This reverts commit a521f2e.
TransitionConfig, Transition, InvokeConfig, StateConfig, and MachineConfig now accept an optional TStates extends string = string generic. When callers supply it, initial and transition targets are constrained to that literal union; the default of string preserves the existing behaviour for untyped machines. StateConfig.on keys are now Partial<Record<TEvent['type'], ...>> so event type typos (e.g. 'CANEEL' instead of 'CANCEL') are caught at the createMachine call site rather than silently accepted. Type tests cover both constraints.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: e1fd1ba The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Repository UI (inherited) Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (10)
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (8)
📝 WalkthroughWalkthroughThe PR adds a typed Mosaic state-machine runtime, React hooks, and machine examples. It also refactors delete/leave organization flows into controller/view slices, updates the destructive confirmation component, and adds documentation plus alias configuration for the new hook path. ChangesMosaic state-machine rollout
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 markdownlint-cli2 (0.22.1).claude/skills/mosaic-machine/SKILL.mdmarkdownlint-cli2 wrapper config was not available before execution packages/ui/src/mosaic/machine/ADOPTION.mdmarkdownlint-cli2 wrapper config was not available before execution packages/ui/src/mosaic/machine/README.mdmarkdownlint-cli2 wrapper config was not available before execution Comment |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
Adds a `UseMachineOptions` type that extends `CreateActorOptions` with an optional `onDone` callback, fired once when the machine reaches a final state. Auth flows can now declaratively hand off (navigate, redirect) without a `useEffect` watching `snapshot.status` externally.
Resolves a promise with the first snapshot satisfying a predicate. Rejects when the actor becomes non-active without the predicate passing, or when an optional timeout elapses (WaitForTimeoutError). Eliminates manual subscribe wiring in async tests and flow orchestration.
Adds setTimeout-based delayed transitions via a new `after` key on state nodes — the idiomatic way to model OTP expiry and resend cooldowns without leaking timers into components. Timers are cancelled on state exit and on stop(), so they never outlive the state or the actor.
No auth flow or component pulls it in; deferred()+tick() covers test needs. Can be added when something concrete requires it.
Machines already stored the API error in context on failure, but the Destructive component had no error prop and neither section component passed the error through. Users saw the dialog reopen with no feedback. Adds an optional error prop to Destructive and surfaces snapshot.context.error from both DeleteOrganizationReady and LeaveOrganizationReady.
- Guard send() and can() with the started flag so callers using createActor()
directly cannot fire events before start() runs entry actions
- Add tests asserting send/can are no-ops before start()
- Add SAFETY comments (per CLAUDE.md) to all non-as-const casts:
createActor.ts (event as never), createMachine.ts ({} as TContext),
setup.ts (fromPromise src cast), firstFactorMachine.ts (three casts)
- Document in delete/leave-organization machines that the CONFIRM guard
is intentionally delegated to the Destructive component
Replace Set with array-based listener tracking using bitwise NOT for safe removal. Inline normalizeTransitions helper to eliminate function overhead. Use short-circuit operators (&&) instead of if statements in hot paths. Collapse toArray into single ternary expression. Minified size: ~130-150 bytes saved (-1.5-2%). All 2316 tests pass. Zero API changes. - Replace Set<SnapshotListener> with array + indexOf + splice pattern (~40 bytes) - Inline normalizeTransitions via map expression (~60 bytes) - Use reverse iteration (i--) in listener loops for safe removal - Apply && operator in hot paths (useMachine, useMachineLogger) (~15 bytes) - Collapse toArray to single-line ternary expression
…javascript into carp/mosaic-state-machine
Adds TransitionFn as a fourth arm of the Transition union. A function
returning { target?, context? } replaces the guard + assign combo for
the common case; returning undefined is treated as unhandled. Works for
both on-event and always transitions, including recheck() re-evaluation.
Contributor
API Changes Report
Summary
No API Changes DetectedAll packages have stable APIs with no detected changes. Report generated by Break Check Last ran on |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (4)
packages/ui/src/mosaic/block/destructive.tsx (1)
43-47: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low valueReset effect re-runs every render due to an unstable setter.
useControllableState's setter is memoized on[isControlled, onChange]. Consumers pass an inlineonConfirmationValueChange, soonChange(and thereforesetConfirmValue) gets a new identity each render, causing this effect to fire on every render. It's a no-op whileopen, but while closed it repeatedly invokes the change callback. Consider stabilizing the consumer handlers withuseCallback, or resetting based on a ref to avoid the redundant calls.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ui/src/mosaic/block/destructive.tsx` around lines 43 - 47, The reset effect in destructive.tsx is re-running every render because `useControllableState` returns a setter that changes identity when `onConfirmationValueChange` is passed inline. Stabilize the consumer callback used by `useControllableState` in `Destructive` (or otherwise avoid depending on the unstable setter in the `useEffect`) so the reset only runs when `open` changes. Update the `useEffect` dependency pattern around `confirmValue`/`setConfirmValue` to prevent repeated change callbacks while the dialog is closed.packages/ui/src/mosaic/machines/signInMachine.ts (1)
42-42: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd an explicit return type to the exported
createSignInMachine.Unlike
createDeleteOrgMachine, this exported factory relies on inferred return typing. Annotating it (e.g.StateMachine<SignInContext, SignInEvent>) keeps the public machine surface stable and self-documenting.As per coding guidelines ("Always define explicit return types for functions, especially public APIs") and based on learnings to enforce explicit return type annotations for exported functions and public APIs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ui/src/mosaic/machines/signInMachine.ts` at line 42, Add an explicit return type to the exported createSignInMachine factory so its public API is stable and self-documenting. Update the createSignInMachine signature to annotate the machine type explicitly, following the pattern used by createDeleteOrgMachine and the other exported machine factories in this module, rather than relying on inference.Sources: Coding guidelines, Learnings
packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts (1)
49-53: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueOptional: the
event.type === 'TYPE'guard is redundant here.This
TYPEhandler only ever receives theTYPEmember at runtime, so the ternary fallback: {}is dead. Using thesetup()factory'sassign(which narrowsecontextually) would let you writeassign((_, e) => ({ confirmValue: e.value }))without the manual discriminant check. Not blocking since this is a fixture.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts` around lines 49 - 53, The TYPE transition in delete-organization-machine is over-defensive because the handler only receives the TYPE event, so the `event.type === 'TYPE'` fallback is unnecessary. Update the `TYPE` action in the `assign` for `DeleteOrgContext` to rely on the contextual event typing from `setup()` and directly map `e.value` to `confirmValue`, removing the dead ternary branch.packages/ui/src/mosaic/machine/setup.ts (1)
41-41: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider an explicit return type for the public
setupfactory.
setupis an exported public API but its return type is inferred. The inner factories are individually annotated, so an explicit interface here would make the public surface self-documenting and guard against accidental shape drift.As per coding guidelines: "Always define explicit return types for functions, especially public APIs."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ui/src/mosaic/machine/setup.ts` at line 41, The exported setup factory currently relies on inferred return type, so make its public API explicit by adding a named return type/interface for setup and annotating the setup<TContext, TEvent> function accordingly; use the existing inner factory types in setup.ts to define the returned shape and ensure the exported surface stays self-documenting and stable.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/mosaic-machine/SKILL.md:
- Line 26: The wording around setup<TContext, TEvent>() is too broad:
fromPromise should be described as the typed helper only for promise-backed
invoke configurations, not all invokes. Update the SKILL.md guidance near
setup/createMachine/assign/fromPromise to state that fromPromise narrows the
resolved type to e.output in onDone.actions only when the invoke returns a
promise, and avoid implying it applies to every invoke configuration.
In `@packages/ui/src/mosaic/block/destructive.tsx`:
- Around line 64-75: The error message rendered by the destructive block is not
announced to assistive tech because it is only a plain paragraph. Update the Box
in destructive.tsx so the error container uses an accessible live announcement
such as role="alert" or aria-live="assertive" while keeping the existing error
rendering logic in place. Locate the conditional error block in the destructive
component and add the ARIA attribute directly on the Box/p element so screen
readers announce failed destructive actions immediately.
In `@packages/ui/src/mosaic/machine/__tests__/patterns.test.ts`:
- Around line 44-64: The submitting invoke in makeSignInMachine only uses
activeStrategy to choose between emailFn and socialFn, so the selected social
provider is lost. Update the social path in the invoke to pass the chosen
strategy through to socialFn, and make the machine context/actions in
makeSignInMachine preserve the CLICK_SOCIAL strategy value so provider-specific
behavior remains available when this pattern is copied.
In `@packages/ui/src/mosaic/machine/__tests__/wizard-migration.test.tsx`:
- Around line 482-508: The current Wizard AFTER test in
wizard-migration.test.tsx uses a no-op GOTO to the same step, which never
publishes a new snapshot and does not validate useSelector behavior. Update the
StepIndicator/useSelector scenario to trigger a real actor transition that emits
a new snapshot while keeping s.value unchanged, then assert renders does not
increment. Use the existing createWizardMachine, createActor, and useSelector
setup to add a context-only or otherwise unrelated transition that preserves the
selected value but still notifies subscribers.
- Around line 173-175: The test helper actorAt is returning an unstarted actor,
so lifecycle-dependent assertions in wizard-migration.test.tsx are not actually
exercising a running machine. Update actorAt to start the actor before returning
it, and make sure any direct recheck() usage in the affected tests also operates
on a started actor so send, can, and subscribe behavior is validated against the
real lifecycle.
In `@packages/ui/src/mosaic/machine/ADOPTION.md`:
- Around line 391-399: The submit invoke in the `submitting` state is erasing
the typed event by casting to `any`; update the `invoke.src` handler to use the
existing `SignInEvent` shape and carry `identifier` through the typed
event/context instead of `(event as any)`. Keep the example fully typed by
referencing the `submitting` state and `signIn.create` call, and remove the
`any` cast while preserving the same payload flow.
- Around line 124-159: The waitlist machine still closes over external async
dependencies instead of using the factory/context pattern. Update the
`waitlistMachine` example so `clerk`, `navigate`, and `afterJoinWaitlistUrl` are
provided through a machine factory or stored in machine context rather than read
from module scope. Use the existing `createMachine`-based `waitlistMachine` and
its `invoke`/`success.entry` logic as the places to thread those dependencies in
for easier testing and consistency with the authoring guidance.
In `@packages/ui/src/mosaic/machine/createActor.ts`:
- Around line 163-188: The invoke completion/error paths in createActor
currently call commit() unconditionally after takeTransition, unlike send,
startAfterTimers, and recheck. Update the onDone and onError handlers to check
the boolean returned by takeTransition before committing, so blocked transitions
do not publish a new snapshot or notify subscribers when the state does not
change.
In `@packages/ui/src/mosaic/machine/README.md`:
- Around line 48-55: The ASCII diagram block in the README is missing a fenced
language label, which triggers markdownlint and reduces highlighting. Update the
fence around the state machine diagram to include an appropriate tag, using the
diagram block near the FETCH/loading/success/failure section so the markdown
parser and tooling recognize it correctly.
In `@packages/ui/src/mosaic/sections/delete-organization-machine.ts`:
- Around line 49-51: The error handling in deleteOrganizationMachine is passing
a stringified exception directly to the UI, which can expose technical text to
end users. Update the assign handler in delete-organization-machine.ts to derive
a user-facing message from the event error (prefer the error’s message field,
with a friendly fallback when unavailable) instead of using String(event.error),
so delete-organization-view.tsx and Destructive receive a safe message. Apply
the same fix to the matching error assignment in leave-organization-machine.ts
to keep both flows consistent.
In `@packages/ui/src/mosaic/sections/leave-organization-machine.ts`:
- Around line 47-52: The `onError` handler in `leave-organization-machine` is
passing `String(event.error)` through to user-facing state, which can include an
unwanted “Error:” prefix. Update the `assign` logic in the `onError` action to
extract `event.error.message` when the rejection is an `Error`, and fall back to
a sensible string for non-Error values. Then adjust the
`leave-organization-machine.test` expectation to match the cleaned message
instead of the prefixed form.
---
Nitpick comments:
In `@packages/ui/src/mosaic/block/destructive.tsx`:
- Around line 43-47: The reset effect in destructive.tsx is re-running every
render because `useControllableState` returns a setter that changes identity
when `onConfirmationValueChange` is passed inline. Stabilize the consumer
callback used by `useControllableState` in `Destructive` (or otherwise avoid
depending on the unstable setter in the `useEffect`) so the reset only runs when
`open` changes. Update the `useEffect` dependency pattern around
`confirmValue`/`setConfirmValue` to prevent repeated change callbacks while the
dialog is closed.
In `@packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts`:
- Around line 49-53: The TYPE transition in delete-organization-machine is
over-defensive because the handler only receives the TYPE event, so the
`event.type === 'TYPE'` fallback is unnecessary. Update the `TYPE` action in the
`assign` for `DeleteOrgContext` to rely on the contextual event typing from
`setup()` and directly map `e.value` to `confirmValue`, removing the dead
ternary branch.
In `@packages/ui/src/mosaic/machine/setup.ts`:
- Line 41: The exported setup factory currently relies on inferred return type,
so make its public API explicit by adding a named return type/interface for
setup and annotating the setup<TContext, TEvent> function accordingly; use the
existing inner factory types in setup.ts to define the returned shape and ensure
the exported surface stays self-documenting and stable.
In `@packages/ui/src/mosaic/machines/signInMachine.ts`:
- Line 42: Add an explicit return type to the exported createSignInMachine
factory so its public API is stable and self-documenting. Update the
createSignInMachine signature to annotate the machine type explicitly, following
the pattern used by createDeleteOrgMachine and the other exported machine
factories in this module, rather than relying on inference.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: f49b6f3b-9b8a-4440-9f9b-e10800af6fd6
📒 Files selected for processing (38)
.changeset/mosaic-state-machine.md.claude/skills/mosaic-machine/SKILL.mdpackages/swingset/next.config.mjspackages/swingset/src/stories/destructive.stories.tsxpackages/swingset/tsconfig.jsonpackages/ui/src/mosaic/block/destructive.tsxpackages/ui/src/mosaic/machine/ADOPTION.mdpackages/ui/src/mosaic/machine/README.mdpackages/ui/src/mosaic/machine/__tests__/delete-organization-machine.tspackages/ui/src/mosaic/machine/__tests__/machine.test.tspackages/ui/src/mosaic/machine/__tests__/patterns.test.tspackages/ui/src/mosaic/machine/__tests__/useMachine.test.tsxpackages/ui/src/mosaic/machine/__tests__/wizard-migration.test.tsxpackages/ui/src/mosaic/machine/assign.tspackages/ui/src/mosaic/machine/createActor.tspackages/ui/src/mosaic/machine/createMachine.tspackages/ui/src/mosaic/machine/setup.tspackages/ui/src/mosaic/machine/types.test-d.tspackages/ui/src/mosaic/machine/types.tspackages/ui/src/mosaic/machine/useMachine.tspackages/ui/src/mosaic/machines/__tests__/firstFactorMachine.test.tspackages/ui/src/mosaic/machines/__tests__/signInMachine.test.tspackages/ui/src/mosaic/machines/__tests__/test-utils.tspackages/ui/src/mosaic/machines/firstFactorMachine.tspackages/ui/src/mosaic/machines/signInMachine.tspackages/ui/src/mosaic/sections/__tests__/delete-organization-machine.test.tspackages/ui/src/mosaic/sections/__tests__/delete-organization-view.test.tsxpackages/ui/src/mosaic/sections/__tests__/leave-organization-machine.test.tspackages/ui/src/mosaic/sections/__tests__/leave-organization-view.test.tsxpackages/ui/src/mosaic/sections/delete-organization-controller.tsxpackages/ui/src/mosaic/sections/delete-organization-machine.tspackages/ui/src/mosaic/sections/delete-organization-view.tsxpackages/ui/src/mosaic/sections/delete-organization.tsxpackages/ui/src/mosaic/sections/leave-organization-controller.tsxpackages/ui/src/mosaic/sections/leave-organization-machine.tspackages/ui/src/mosaic/sections/leave-organization-view.tsxpackages/ui/src/mosaic/sections/leave-organization.tsxreferences/mosaic-architecture.md
Comment on lines
+482
to
+508
| describe('Wizard AFTER — useSelector scopes re-renders to the step slice', () => { | ||
| it('a stepper re-renders on navigation but not on an unrelated context change', () => { | ||
| const machine = createWizardMachine([{ id: 'intro' }, { id: 'details', guard: () => true }]); | ||
| // Seed at 'intro' (furthest-reachable would land on 'details' otherwise). | ||
| const actor = createActor(machine, { snapshot: { value: 'intro' } }); | ||
| actor.start(); | ||
|
|
||
| const renders = vi.fn(); | ||
| function StepIndicator() { | ||
| const current = useSelector(actor, s => s.value); | ||
| renders(); | ||
| return <output data-testid='current'>{current}</output>; | ||
| } | ||
|
|
||
| render(<StepIndicator />); | ||
| expect(renders).toHaveBeenCalledTimes(1); | ||
| expect(screen.getByTestId('current')).toHaveTextContent('intro'); | ||
|
|
||
| // A GOTO to the current step is a no-op → no notify → no re-render. | ||
| act(() => actor.send({ type: 'GOTO', step: 'intro' })); | ||
| expect(renders).toHaveBeenCalledTimes(1); | ||
|
|
||
| // A real navigation changes the selected slice → exactly one re-render. | ||
| act(() => actor.send({ type: 'NEXT' })); | ||
| expect(renders).toHaveBeenCalledTimes(2); | ||
| expect(screen.getByTestId('current')).toHaveTextContent('details'); | ||
| }); |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the useSelector test emit a snapshot whose selected value is unchanged.
The current “unrelated context change” assertion sends GOTO to the current step, which is a true no-op and does not notify subscribers. That does not prove useSelector suppresses re-renders when the actor publishes a new snapshot but s.value is unchanged.
Consider adding a context-only transition in this test and asserting renders remains unchanged after that event.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/ui/src/mosaic/machine/__tests__/wizard-migration.test.tsx` around
lines 482 - 508, The current Wizard AFTER test in wizard-migration.test.tsx uses
a no-op GOTO to the same step, which never publishes a new snapshot and does not
validate useSelector behavior. Update the StepIndicator/useSelector scenario to
trigger a real actor transition that emits a new snapshot while keeping s.value
unchanged, then assert renders does not increment. Use the existing
createWizardMachine, createActor, and useSelector setup to add a context-only or
otherwise unrelated transition that preserves the selected value but still
notifies subscribers.
Member
Author
There was a problem hiding this comment.
Valid point — the GOTO-to-same-step test doesn't prove useSelector actually filters a new snapshot where the selected slice is unchanged. Skipping for this PR: adding a context-only transition that emits a new snapshot without changing s.value would require a new event on the wizard machine, which is out of scope here. Filed as a follow-up.
Contributor
There was a problem hiding this comment.
@alexcarpenter Makes sense — thanks for confirming the gap and for filing the follow-up. Agreed that introducing a wizard-specific context-only event just to prove the useSelector behavior would broaden this test fixture beyond the scope of this PR, so I'm good to defer it.
🧠 Learnings used
Learnt from: alexcarpenter
Repo: clerk/javascript PR: 8593
File: packages/ui/src/elements/ClipboardInput.tsx:0-0
Timestamp: 2026-05-19T17:58:25.594Z
Learning: When styling native HTML `<input type="text">` (or other single-line text inputs), applying `textOverflow: 'ellipsis'` by itself is sufficient—native single-line input behavior provides implicit single-line/overflow handling, so you generally do not need to also set `overflow: 'hidden'` or `whiteSpace: 'nowrap'`. Conversely, if you’re applying ellipsis to non-input/block-level elements (e.g., `<div>`, `<span>`, or other elements), ensure `whiteSpace: 'nowrap'` and `overflow: 'hidden'` are included alongside `textOverflow: 'ellipsis'` so the ellipsis can render.
Learnt from: alexcarpenter
Repo: clerk/javascript PR: 8922
File: packages/ui/src/primitives/Input.tsx:30-33
Timestamp: 2026-06-18T21:53:41.119Z
Learning: When building SVG `data:` URIs, ensure any interpolated theme color token won’t introduce reserved characters. In particular, `theme.colors.$white` resolves to the CSS named color string `'white'` (no `#`), so interpolating it into an SVG `data:` URI does not create `#`-related URI breakage and does not require URL-encoding for that token specifically. If a token resolves to a hex color (e.g., `#fff`), then `#` must be treated as a reserved character and should be encoded/escaped accordingly.
- Gate commit() on takeTransition return in invoke onDone/onError handlers so blocked entry guards don't publish spurious snapshots - Use error.message instead of String(error) in delete/leave org machines to avoid surfacing "Error: nope"-style technical text to users - Add role='alert' to error box in Destructive component for screen readers - Pass selected social strategy through to socialFn in patterns.test.ts - Use factory pattern for waitlistMachine example in ADOPTION.md - Remove any cast in signInStart machine example by storing identifier in context on SUBMIT transitions - Add text language tag to ASCII diagram fence in README.md - Narrow fromPromise description in SKILL.md
This was referenced Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
We have several approaches to handling flows in component code, domain modeling and state syncing spread across
useEffects which makes it difficult to without rendering a component. This adds a lightweight state machine library with the goal of standardizing flow patterns.Why not XState
XState is the obvious reference, and the API design follows XState v5 closely but ~9x smaller.
What's in this PR
packages/ui/src/mosaic/machine/delete-organizationandleave-organizationMosaic component sections migrated as a proof of conceptsignInMachineandfirstFactorMachinemodelled but not wired to components yetpatterns.test.tsdocuments how real Clerk patterns map to machine primitivesChecklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit