@persona/design-system 0.5.1 → 0.6.0

package/dist/{useFormField-C-K1lgmv.mjs → useFormField-DhYd6bNn.mjs}

@@ -1,4 +1,4 @@
-import { n as useFormGroup } from "./useFormGroup-y-duFylq.mjs";
+import { n as useFormGroup } from "./useFormGroup-DWVW7A9f.mjs";
 import { createContext, useContext } from "react";
 //#region components/FormControl/useFormField.ts
 const FormControlContext = createContext({});
@@ -22,4 +22,4 @@ const useFormField = (props) => {
 //#endregion
 export { useFormField as n, FormControlContext as t };
 
-//# sourceMappingURL=useFormField-C-K1lgmv.mjs.map
+//# sourceMappingURL=useFormField-DhYd6bNn.mjs.map

package/dist/{useFormField-C-K1lgmv.mjs.map → useFormField-DhYd6bNn.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"useFormField-C-K1lgmv.mjs","names":[],"sources":["../components/FormControl/useFormField.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\n\nimport useFormGroup from 'design-system/components/ConfigFormGroup/useFormGroup';\nimport type ErrorProps from 'design-system/types/ErrorProps';\n\nexport interface FormControlContextProps extends ErrorProps {\n  inputId?: string;\n  helperTextId?: string;\n  errorTextId?: string;\n  warningTextId?: string;\n  labelId?: string;\n  disabled?: boolean;\n  maxLength?: number;\n  configField?: boolean;\n}\n\nexport const FormControlContext = createContext<FormControlContextProps>({});\n\nconst useFormField = (props: Partial<FormControlContextProps>) => {\n  const group = useFormGroup();\n  const field = useContext(FormControlContext);\n\n  const inputId = props.inputId ?? field.inputId;\n\n  return {\n    configField: props.configField ?? group.configField,\n    hasError: props.hasError ?? field.hasError,\n    hasWarning: props.hasWarning ?? field.hasWarning,\n    inputId,\n    helperTextId: props.helperTextId ?? field.helperTextId,\n    errorTextId: props.errorTextId ?? field.errorTextId,\n    warningTextId: props.warningTextId ?? field.warningTextId,\n    labelId: props.labelId ?? field.labelId,\n    disabled: props.disabled ?? field.disabled,\n    maxLength: props.maxLength ?? field.maxLength,\n  };\n};\n\nexport default useFormField;\n"],"mappings":";;;AAgBA,MAAa,qBAAqB,cAAuC,EAAE,CAAC;AAE5E,MAAM,gBAAgB,UAA4C;CAChE,MAAM,QAAQ,cAAc;CAC5B,MAAM,QAAQ,WAAW,mBAAmB;CAE5C,MAAM,UAAU,MAAM,WAAW,MAAM;AAEvC,QAAO;EACL,aAAa,MAAM,eAAe,MAAM;EACxC,UAAU,MAAM,YAAY,MAAM;EAClC,YAAY,MAAM,cAAc,MAAM;EACtC;EACA,cAAc,MAAM,gBAAgB,MAAM;EAC1C,aAAa,MAAM,eAAe,MAAM;EACxC,eAAe,MAAM,iBAAiB,MAAM;EAC5C,SAAS,MAAM,WAAW,MAAM;EAChC,UAAU,MAAM,YAAY,MAAM;EAClC,WAAW,MAAM,aAAa,MAAM;EACrC"}
+{"version":3,"file":"useFormField-DhYd6bNn.mjs","names":[],"sources":["../components/FormControl/useFormField.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\n\nimport useFormGroup from 'design-system/components/ConfigFormGroup/useFormGroup';\nimport type ErrorProps from 'design-system/types/ErrorProps';\n\nexport interface FormControlContextProps extends ErrorProps {\n  inputId?: string;\n  helperTextId?: string;\n  errorTextId?: string;\n  warningTextId?: string;\n  labelId?: string;\n  disabled?: boolean;\n  maxLength?: number;\n  configField?: boolean;\n}\n\nexport const FormControlContext = createContext<FormControlContextProps>({});\n\nconst useFormField = (props: Partial<FormControlContextProps>) => {\n  const group = useFormGroup();\n  const field = useContext(FormControlContext);\n\n  const inputId = props.inputId ?? field.inputId;\n\n  return {\n    configField: props.configField ?? group.configField,\n    hasError: props.hasError ?? field.hasError,\n    hasWarning: props.hasWarning ?? field.hasWarning,\n    inputId,\n    helperTextId: props.helperTextId ?? field.helperTextId,\n    errorTextId: props.errorTextId ?? field.errorTextId,\n    warningTextId: props.warningTextId ?? field.warningTextId,\n    labelId: props.labelId ?? field.labelId,\n    disabled: props.disabled ?? field.disabled,\n    maxLength: props.maxLength ?? field.maxLength,\n  };\n};\n\nexport default useFormField;\n"],"mappings":";;;AAgBA,MAAa,qBAAqB,cAAuC,EAAE,CAAC;AAE5E,MAAM,gBAAgB,UAA4C;CAChE,MAAM,QAAQ,cAAc;CAC5B,MAAM,QAAQ,WAAW,mBAAmB;CAE5C,MAAM,UAAU,MAAM,WAAW,MAAM;AAEvC,QAAO;EACL,aAAa,MAAM,eAAe,MAAM;EACxC,UAAU,MAAM,YAAY,MAAM;EAClC,YAAY,MAAM,cAAc,MAAM;EACtC;EACA,cAAc,MAAM,gBAAgB,MAAM;EAC1C,aAAa,MAAM,eAAe,MAAM;EACxC,eAAe,MAAM,iBAAiB,MAAM;EAC5C,SAAS,MAAM,WAAW,MAAM;EAChC,UAAU,MAAM,YAAY,MAAM;EAClC,WAAW,MAAM,aAAa,MAAM;EACrC"}

package/dist/{useFormGroup-y-duFylq.mjs → useFormGroup-DWVW7A9f.mjs}

@@ -11,4 +11,4 @@ const useFormGroup = (props) => {
 //#endregion
 export { useFormGroup as n, FormGroupContext as t };
 
-//# sourceMappingURL=useFormGroup-y-duFylq.mjs.map
+//# sourceMappingURL=useFormGroup-DWVW7A9f.mjs.map

package/dist/{useFormGroup-y-duFylq.mjs.map → useFormGroup-DWVW7A9f.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"useFormGroup-y-duFylq.mjs","names":[],"sources":["../components/ConfigFormGroup/useFormGroup.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\n\nexport interface FormGroupContextProps {\n  configField?: boolean;\n  /**\n   * The z-index to use when labels are rendered as tooltips (e.g. when configField is true).\n   */\n  labelTooltipZIndex?: number;\n}\n\nexport const FormGroupContext = createContext<FormGroupContextProps>({});\n\nconst useFormGroup = (props?: Partial<FormGroupContextProps>) => {\n  const field = useContext(FormGroupContext);\n\n  return {\n    configField: props?.configField ?? field.configField,\n    labelTooltipZIndex: props?.labelTooltipZIndex ?? field.labelTooltipZIndex,\n  };\n};\n\nexport default useFormGroup;\n"],"mappings":";;AAUA,MAAa,mBAAmB,cAAqC,EAAE,CAAC;AAExE,MAAM,gBAAgB,UAA2C;CAC/D,MAAM,QAAQ,WAAW,iBAAiB;AAE1C,QAAO;EACL,aAAa,OAAO,eAAe,MAAM;EACzC,oBAAoB,OAAO,sBAAsB,MAAM;EACxD"}
+{"version":3,"file":"useFormGroup-DWVW7A9f.mjs","names":[],"sources":["../components/ConfigFormGroup/useFormGroup.ts"],"sourcesContent":["import { createContext, useContext } from 'react';\n\nexport interface FormGroupContextProps {\n  configField?: boolean;\n  /**\n   * The z-index to use when labels are rendered as tooltips (e.g. when configField is true).\n   */\n  labelTooltipZIndex?: number;\n}\n\nexport const FormGroupContext = createContext<FormGroupContextProps>({});\n\nconst useFormGroup = (props?: Partial<FormGroupContextProps>) => {\n  const field = useContext(FormGroupContext);\n\n  return {\n    configField: props?.configField ?? field.configField,\n    labelTooltipZIndex: props?.labelTooltipZIndex ?? field.labelTooltipZIndex,\n  };\n};\n\nexport default useFormGroup;\n"],"mappings":";;AAUA,MAAa,mBAAmB,cAAqC,EAAE,CAAC;AAExE,MAAM,gBAAgB,UAA2C;CAC/D,MAAM,QAAQ,WAAW,iBAAiB;AAE1C,QAAO;EACL,aAAa,OAAO,eAAe,MAAM;EACzC,oBAAoB,OAAO,sBAAsB,MAAM;EACxD"}

package/dist/useTruncation.d.mts

@@ -1,4 +1,4 @@
-import { i as ComboboxOption } from "./ComboboxBase-Ds_i3K2m.mjs";
+import { i as ComboboxOption } from "./ComboboxBase-DBLJYQrh.mjs";
 import { MutableRefObject, RefObject } from "react";
 
 //#region components/Combobox/useTruncation.d.ts

package/llms.txt

@@ -17,6 +17,7 @@ For exact prop types, prefer the published type declarations (`dist/**/*.d.mts`,
 - [Tokens](skills/ui-authoring/TOKENS.md): Color / Spacing / Typography selection and catalog, radius, charts
 - [Patterns](skills/ui-authoring/PATTERNS.md): forms, layout, indicators, feedback, empty states, charts, panels
 - [Components](skills/ui-authoring/COMPONENTS.md): which PDS component to use (and its import path); APIs live in that component's `.mdx` when one exists, otherwise in `dist/components/<Name>/index.d.mts`
+- [design-system-component-authoring](skills/design-system-component-authoring/SKILL.md): authoring a new PDS component in this repo — clarifying scope, component conventions, prop interface patterns
 
 ## Imports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/design-system",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "React components for Persona UI",
   "keywords": [
     "tanstack-intent"
@@ -114,6 +114,7 @@
     "./lib/useControlled": "./dist/lib/useControlled.mjs",
     "./lib/useEmbeddedSurface": "./dist/lib/useEmbeddedSurface.mjs",
     "./lib/useIsOverflow": "./dist/lib/useIsOverflow.mjs",
+    "./lib/useModalInsetRight": "./dist/lib/useModalInsetRight.mjs",
     "./lib/useOutsideClick": "./dist/lib/useOutsideClick.mjs",
     "./lib/useResizablePanel": "./dist/lib/useResizablePanel.mjs",
     "./lib/useScrollOverflow": "./dist/lib/useScrollOverflow.mjs",
@@ -346,6 +347,7 @@
       "./lib/useControlled": "./dist/lib/useControlled.mjs",
       "./lib/useEmbeddedSurface": "./dist/lib/useEmbeddedSurface.mjs",
       "./lib/useIsOverflow": "./dist/lib/useIsOverflow.mjs",
+      "./lib/useModalInsetRight": "./dist/lib/useModalInsetRight.mjs",
       "./lib/useOutsideClick": "./dist/lib/useOutsideClick.mjs",
       "./lib/useResizablePanel": "./dist/lib/useResizablePanel.mjs",
       "./lib/useScrollOverflow": "./dist/lib/useScrollOverflow.mjs",

package/skills/design-system-component-authoring/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: design-system-component-authoring
+description: Use when building a new Persona design system component under packages/design-system/components/, or turning a designer's description, Figma frame, or AI-generated first draft into one. Also use when determining prop interfaces, weighing `children` vs a typed `items` array, questioning a composer pattern, spotting props that allow impossible states, finding hardcoded colors or missing tokens, or seeing a component rebuild what an existing DS primitive already does.
+---
+
+# Design System Component Authoring
+
+## Overview
+
+Core principle: **model the real requirement with the smallest prop interface that makes impossible
+states unrepresentable, compose existing design-system components instead of rebuilding them, and
+ask before inventing scope.** A first pass built this way needs almost no engineer refactoring.
+
+These components usually start from a designer's description (the designer may not code), so the
+failure mode is predictable: guessing at scope, inventing props, reaching for the most
+flexible-looking type. Prefer clarifying questions and small, correct interfaces over feature-rich
+guesses.
+
+## When to use
+
+- Building a new component under `packages/design-system/components/`.
+- Turning a designer's description, a Figma frame, or an AI draft into a real DS component.
+
+**REQUIRED BACKGROUND — load this too:**
+
+- `ui-authoring` — design tokens (`Color`, `Spacing`, `Typography`), when to use `Stack`/`HStack`/`Text` instead of styled elements, and its `COMPONENTS.md`/`PATTERNS.md` catalog of existing components to compose from (also browse `packages/design-system/components/`).
+
+## Canonical example
+
+`packages/design-system/components/Breadcrumbs/` is the example to imitate: a constrained
+`BreadcrumbsItemProps[]` rendered by a private `Breadcrumb`; `onEdit?` gating inline editing with no
+`editable` boolean; composition from `IconButton`, `Input`, `Link`, `HStack`, `Paragraph`,
+`Tooltip`; semantic theme tokens; a `DEFAULT_EDIT_MAX_LENGTH` constant; and a barrel `index.ts`
+plus `Breadcrumbs.mdx` with `<Controls />`.
+
+## Step 1 — Clarify before building (do NOT assume)
+
+Ask the designer whenever scope, states, sizes, max lengths, content shape, or state ownership are
+unspecified — and never add props the designer didn't ask for. **REQUIRED:** read
+`clarifying-scope.md` (in this skill directory) for the exact questions to ask.
+
+## Step 2 — Design the prop interface
+
+The props ARE the contract; make incorrect usage impossible to express. **REQUIRED:** read
+`prop-interface-patterns.md` (in this skill directory) for the rules, the do/don't table, and the
+rationalizations that lead to bad interfaces.
+
+## Step 3 — Build it
+
+Compose from existing DS components (never copy their CSS), style only with design tokens, follow
+the standard file layout with a barrel `index.ts`, use real aria affordances, and ship a
+`ComponentName.mdx`. Also add a row to
+`packages/design-system/skills/ui-authoring/COMPONENTS.md` (Component / Use for / Import) so UI
+authors pick the new component instead of reinventing it. **REQUIRED:** read
+`component-conventions.md` (in this skill directory) for each of those in detail.
+
+## Step 4 — Handoff
+
+Add a component `.mdx` page in `persona-id/design-site`, following the structure of existing
+component docs, and open a separate PR. If this session cannot access or write to that repository,
+explicitly flag the documentation PR as a required follow-up rather than marking it complete.
+
+If you open a PR, open it as a **draft** so an engineer can pick it up and review before it goes to
+wider engineering review.
+
+## Red flags — STOP and reconsider (or ask the designer)
+
+- A boolean and a callback that mean the same thing (`editable` + `onEdit`).
+- `loading` and `data` (or `error` and `value`) that can both be set at once.
+- A `variant`/status string union with exactly two options.
+- `title` / `label` / tooltip text typed as `ReactNode`.
+- `children` accepted where the design wants a fixed set of items.
+- `styled(SomeDSComponent)` with hardcoded color overrides or arbitrary restyling — layout-only tweaks (margin/width/alignment) are fine — or CSS copied from another component.
+- A prop, variant, or feature the designer never asked for (`fullWidth`, extra sizes), or spreading arbitrary `...props` onto the root.
+- A context provider whose only job is passing a `size`/`variant`.
+- Hardcoded hex/px, or `Core*` foundational tokens where a semantic token exists.
+- Missing `index.ts`, `.mdx`, aria attributes, or a `COMPONENTS.md` picker row.
+- You assumed a constraint (some items editable, a specific max length) instead of asking.
+- MDX docs with long, difficult-to-scan prose.

package/skills/design-system-component-authoring/clarifying-scope.md

@@ -0,0 +1,18 @@
+# Clarifying scope with the designer
+
+Stop and ask when any of the following is unspecified. **Never invent constraints or scope.** A
+short question now prevents a rebuild later.
+
+| Designer says / leaves unstated               | Ask before coding                                                                                                                                                                                 |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "the items can be editable"                   | Are **all** items editable, or only some? Default: assume all behave the same. Do **not** invent a per-item `editable` flag.                                                                      |
+| A text/rename input                           | What is the max length we'd reasonably allow? Pick a sensible default and confirm it.                                                                                                             |
+| A "status" / "loading" component              | What are the exact, mutually-exclusive states? (drives the prop interface)                                                                                                                       |
+| Sizes/variants mentioned loosely              | Which sizes/variants actually exist? Don't add extras "for completeness".                                                                                                                        |
+| "designers can put whatever they want inside" | Should the contents be a constrained set of typed items (`items: ItemProps[]` + private child) or a genuinely open `children` slot? Surface this tradeoff — don't silently default to `children`. |
+| Nothing about ownership                       | Should the caller own the value (`value` + `onChange`) or should the component manage it internally?                                                                                              |
+
+Do **not** add props, variants, or features the designer did not ask for (e.g. `fullWidth`, extra
+variants, spreading arbitrary `...props` onto the root). A single optional `className` for external
+layout composition is fine (see `BreadcrumbsProps`); inventing feature props is not. If you think
+one is needed, propose it and ask — don't ship it silently.

package/skills/design-system-component-authoring/component-conventions.md

@@ -0,0 +1,70 @@
+# Component conventions (compose, tokens, structure, a11y, docs)
+
+## Compose, don't recreate
+
+- Build from existing DS components — `Button`/`IconButton`, `Link`, `Input`, `Stack`/`HStack`,
+  `Text` (`Heading`/`Paragraph`/`Label`), `Tooltip`, `Spinner`, `Sticker`, etc. Check the
+  `ui-authoring` component catalog (`COMPONENTS.md`, `PATTERNS.md`) and
+  `packages/design-system/components/` before writing anything custom.
+- **Use each component directly and keep its built-in styles.** Never copy/paste a DS component's
+  CSS into a `styled.div`. Wrapping a DS component with `styled(Component)` for _layout/positioning_
+  tweaks (margin, width, alignment) is fine, and adjusting a state with a _semantic token_ (e.g. `theme.color.text.tertiary`) is acceptable — but don't hardcode colors or arbitrarily change a component's visual identity. If the design truly needs a different look, that's a question for the designer/engineer, not a silent restyle.
+- Replace raw flex wrappers with `Stack`/`HStack`. Do not re-implement `display: flex; gap` that
+  `HStack` already provides.
+- Reach for a semantic HTML element (`nav`, `ul`/`li`, `button`) only when **no** DS component
+  covers the need.
+
+## Style with tokens
+
+- All CSS values come from design tokens (see `ui-authoring`). No hardcoded hex or px.
+- **Prefer semantic tokens over foundational ones:** `theme.color.text.tertiary` /
+  `Color.TextPrimary` over `Color.CorePurple500`. Foundational `Core*` colors are a last resort and
+  need a comment.
+- Consolidate nested styled elements — every wrapper must earn its place.
+
+## File structure
+
+```
+packages/design-system/components/ComponentName/
+├── ComponentName.tsx          # public component (+ a private child .tsx if using an items array)
+├── index.ts                   # barrel export
+├── ComponentName.stories.tsx  # stories per variant/state
+├── ComponentName.spec.tsx     # tests
+└── ComponentName.mdx          # docs
+```
+
+- **Name files/exports for what they are.** Name a plural + singular pair `Breadcrumbs` +
+  `Breadcrumb` (each file exports the component of its own name), not `Breadcrumbs` +
+  `BreadcrumbSingle`. When the singular is a constrained-items child, keep it a _private_ child —
+  don't barrel-export it.
+- `index.ts` re-exports the public component (default + named) and its public types only, not
+  private children. See `Breadcrumbs/index.ts`: it exports `Breadcrumbs` and the item/size types,
+  but not the private `Breadcrumb`.
+- Extract self-contained logic (clipboard, inline-edit lifecycle, debouncing) into a `useX` hook so
+  the component file stays focused on presentation and structure.
+- **Don't over-engineer.** Do not add a context provider just to thread a `size`/`variant` — pass it
+  as a prop. Context is for genuinely cross-cutting state shared across deeply nested descendants.
+
+## Accessibility
+
+Use proper roles/landmarks and aria affordances: `aria-label`, `aria-current`, `aria-busy`,
+`aria-hidden` on decorative elements, and label association for inputs. Manage focus for interactive
+widgets. Stories should set `parameters: { a11y: { test: 'error' } }`, and tests should target
+accessible roles/labels (avoid `data-testid`).
+
+## Document in Storybook
+
+Add `ComponentName.mdx` alongside the stories:
+
+```tsx
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
+import * as stories from './ComponentName.stories';
+
+<Meta of={stories} />
+
+<Canvas of={stories.Playground} />
+<Controls of={stories.Playground} />
+```
+
+Keep MDX prose readable and follow the repository's Storybook conventions for titles and Chromatic
+settings.

package/skills/design-system-component-authoring/prop-interface-patterns.md

@@ -0,0 +1,30 @@
+# Prop interface patterns
+
+The props ARE the contract. Make incorrect usage impossible to express.
+
+| Rule                                              | Instead of                                                      | Prefer                                                                                                                                           |
+| ------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Callback implies capability                       | `editable: boolean; onEdit: () => void`                         | `onEdit?: (v: string) => void` — editability = `onEdit != null`                                                                                  |
+| Make impossible states unrepresentable            | `loading?: boolean; data?: Data` (both can be set)              | one discriminated field: `state: { kind: 'loading' } \| { kind: 'ready'; data: Data }`, or derive loading from `data == null`                    |
+| Boolean over a 2-value union                      | `variant: 'default' \| 'compact'`                               | `compact?: boolean` — use a string union only for **3+** real, mutually-exclusive variants                                                       |
+| Text is a string                                  | `title: ReactNode`                                              | `title: string` (+ optional `icon?: IconType` if it needs one). Two typed props beat an arbitrary node                                           |
+| Props are the interface                           | a parallel `interface FooState` layered on `interface FooProps` | let the props type be the interface. One item-shape type for an array (like `BreadcrumbsItemProps`) is fine; a redundant second interface is not |
+| Constrain content when callers shouldn't style it | `children: ReactNode`                                           | `items: ItemProps[]` rendered by a private child component. Use `children` only for genuinely open containers                                    |
+| Right owner for each piece of state               | everything internal, or everything external                     | caller owns meaningful data (`value`/`onChange`); component keeps transient UI state (`isOpen`, `isEditing`) internal                            |
+
+**Impossible-states rule of thumb:** if two optional props describe the same thing at different
+times (loading vs loaded data, error vs value), collapse them so only one can exist at a time.
+
+## Common rationalizations
+
+| Rationalization                                               | Reality                                                                                                                                               |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll add `editable` for clarity even though `onEdit` exists" | Redundant state that can contradict itself. Presence of `onEdit` _is_ editability.                                                                    |
+| "Separate optional `loading` and `data` is flexible"          | It lets callers represent impossible states. Model one-or-the-other.                                                                                  |
+| "A `variant` union is more extensible than a boolean"         | Two-value unions add ceremony now for a third case that may never come. Boolean until there are 3+ real variants.                                     |
+| "A `ReactNode` title is more flexible"                        | It invites arbitrary markup you can't style or constrain. `string` (+ optional `icon`) covers the real need.                                          |
+| "`children` lets designers compose freely"                    | For DS components that usually means inconsistent, unstyleable content. Prefer a typed `items[]` + private child unless it's truly an open container. |
+| "I'll add `fullWidth`/`className` while I'm here"              | Unrequested API surface. Ask first.                                                                                                                    |
+| "Some list items are probably not editable"                   | Don't invent constraints. Assume uniform behavior or ask the designer.                                                                                |
+| "A context provider is cleaner for size"                      | Overkill for one value. Pass the prop.                                                                                                                  |
+| "I'll copy the Button styles so it matches"                    | Duplicated styles drift. Use `Button` directly and keep its styles.                                                                                    |