@12-apps/ui 6.63.1 → 6.64.0

package/dist/typography/Blockquote.js

@@ -1,7 +1,7 @@
 import {
   Blockquote
-} from "../chunk-PUNSVPME.js";
-import "../chunk-SSX5ITPM.js";
+} from "../chunk-RDLZUV2L.js";
+import "../chunk-XJAD6E3V.js";
 import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-YKCAJ2TN.js";

package/dist/typography/Code.js

@@ -1,8 +1,8 @@
 import "../chunk-DURAH4VI.js";
 import {
   Code
-} from "../chunk-6V3HKKNC.js";
-import "../chunk-SSX5ITPM.js";
+} from "../chunk-TTCVYY2B.js";
+import "../chunk-XJAD6E3V.js";
 import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-YKCAJ2TN.js";

package/dist/typography/Heading.js

@@ -1,8 +1,8 @@
 import "../chunk-6GP2DOOO.js";
 import {
   Heading
-} from "../chunk-63D2UYRJ.js";
-import "../chunk-P7OGKSBF.js";
+} from "../chunk-GBVVI35T.js";
+import "../chunk-KZYCQH7O.js";
 import "../chunk-NNKMYH6U.js";
 import "../chunk-TYJR4GOF.js";
 import "../chunk-PT6TCWIW.js";
@@ -13,7 +13,7 @@ import "../chunk-AG66JBNH.js";
 import "../chunk-FZXKH2ZT.js";
 import "../chunk-26X4CZVR.js";
 import "../chunk-O6MJWHU5.js";
-import "../chunk-SSX5ITPM.js";
+import "../chunk-XJAD6E3V.js";
 import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-PZ5AY32C.js";

package/dist/user-avatar.js

@@ -1,22 +1,22 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-VLRHESS2.js";
+} from "./chunk-MJ6EAND6.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-AKC5GRJF.js";
-import "./chunk-NVXRV3PL.js";
+import "./chunk-KARMRTTM.js";
+import "./chunk-7XSCEHGA.js";
 import "./chunk-MTEQEPNY.js";
 import "./chunk-6ZZGK5DT.js";
 import "./chunk-3ZVUNSFF.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
-import "./chunk-J2QIICWP.js";
-import "./chunk-W2TCSYLI.js";
+import "./chunk-W2RXXF7K.js";
+import "./chunk-PLB6WWXW.js";
 import "./chunk-FKUYRQSP.js";
 import "./chunk-HDBP55R3.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-W4O3BTD5.js";
-import "./chunk-JTIKY2D3.js";
+import "./chunk-364NH2NY.js";
+import "./chunk-PPEHBI5O.js";
 import "./chunk-G2FUZALJ.js";
 import "./chunk-TAMIZE4Q.js";
 import "./chunk-AJBRO76D.js";
@@ -33,7 +33,7 @@ import "./chunk-AG66JBNH.js";
 import "./chunk-FZXKH2ZT.js";
 import "./chunk-26X4CZVR.js";
 import "./chunk-O6MJWHU5.js";
-import "./chunk-SSX5ITPM.js";
+import "./chunk-XJAD6E3V.js";
 import "./chunk-F5H2ZXST.js";
 import "./chunk-N3GAFIXG.js";
 import "./chunk-YKCAJ2TN.js";

package/dist/utility/AnimatedIcon.js

@@ -1,11 +1,11 @@
 import "../chunk-H2PTB6FD.js";
 import {
   AnimatedIcon
-} from "../chunk-6K2A4PY5.js";
-import "../chunk-FJKHDKCV.js";
+} from "../chunk-WOXWLJYR.js";
+import "../chunk-B5CUV4ZK.js";
 import "../chunk-KM3Y5TCG.js";
 import "../chunk-HPK33ACY.js";
-import "../chunk-SSX5ITPM.js";
+import "../chunk-XJAD6E3V.js";
 import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-YKCAJ2TN.js";

package/dist/utility/InfiniteScroll.js

@@ -1,9 +1,9 @@
 import "../chunk-H7NA4TXY.js";
 import {
   InfiniteScroll
-} from "../chunk-HBP2OU4Q.js";
-import "../chunk-5KNDAC24.js";
+} from "../chunk-HNFZLXZI.js";
 import "../chunk-Y2X7LYIN.js";
+import "../chunk-5KNDAC24.js";
 import "../chunk-YKCAJ2TN.js";
 import "../chunk-PZ5AY32C.js";
 export {

package/dist/utility/WorkflowStep.js

@@ -1,10 +1,10 @@
 import "../chunk-IO36MEBD.js";
 import {
   WorkflowStep
-} from "../chunk-KRT4WGV5.js";
-import "../chunk-NM65DY2A.js";
-import "../chunk-7PK5IENM.js";
-import "../chunk-ZJGDD54X.js";
+} from "../chunk-HZK4DRGF.js";
+import "../chunk-VNVV6Y2X.js";
+import "../chunk-SV6IQ2YO.js";
+import "../chunk-XKSA4L2X.js";
 import "../chunk-B7ZHEOQQ.js";
 import "../chunk-BRHRK7BK.js";
 import "../chunk-25MSGLNU.js";
@@ -24,7 +24,7 @@ import "../chunk-AG66JBNH.js";
 import "../chunk-FZXKH2ZT.js";
 import "../chunk-26X4CZVR.js";
 import "../chunk-O6MJWHU5.js";
-import "../chunk-SSX5ITPM.js";
+import "../chunk-XJAD6E3V.js";
 import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-YKCAJ2TN.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.63.1",
+  "version": "6.64.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -436,6 +436,10 @@
       "types": "./dist/types/components/form/PhoneInput/index.d.ts",
       "default": "./dist/form/PhoneInput.js"
     },
+    "./form/PickerSheet": {
+      "types": "./dist/types/components/form/PickerSheet/index.d.ts",
+      "default": "./dist/form/PickerSheet.js"
+    },
     "./form/RadioGroup": {
       "types": "./dist/types/components/form/RadioGroup/index.d.ts",
       "default": "./dist/form/RadioGroup.js"

package/src/components/form/PickerSheet/PickerSheet.md

@@ -0,0 +1,119 @@
+# PickerSheet Component
+
+A searchable pick-or-create sheet. A title (with an optional kicker above it), a
+search box, a list of rows that may be a tree, an optional create row, and an
+optional note underneath. On a pointer it is a centred dialog; on a phone it is
+a bottom sheet. It is only the sheet — the trigger that opens it is the
+caller's.
+
+Every word it shows comes from the caller: the package ships no copy for it.
+
+## Purpose and Use Cases
+
+- One picker pattern for every "choose one of these, or add it" field in an
+  editor: a product's category, its kitchen station, the product behind a paid
+  add-on, a recipe component.
+- Use it when the field opens a focused choice of its own. For an inline
+  searchable field use `CreatableSelect`; for a category FILTER (multi-select,
+  parents as headings) use `CategorySelect`; for a command menu use `Command`.
+
+## Props Documentation
+
+- **open** (`boolean`): whether the sheet is shown. The query resets each time it opens.
+- **onClose** (`() => void`): Esc, a tap outside, and the close button. Picking does NOT call it.
+- **kicker** (`string`): small muted line above the title.
+- **title** (`string`, required): the dialog's name — the dialog is `aria-labelledby` it.
+- **searchPlaceholder** (`string`, required): the search box's placeholder.
+- **searchLabel** (`string`, required): the search box's accessible name.
+- **closeLabel** (`string`, required): the close button's accessible name.
+- **items** (`PickerSheetItem[]`, required): the rows, in order.
+  - **id** (`string`): what `onPick` receives.
+  - **label** (`string`): the row's first line.
+  - **meta** (`string`): a muted second line — a category's path, a price.
+  - **indent** (`number`): tree depth, drawn as 28px of left padding per level. Applied only while the query is empty; a search flattens the list, so put the path in `meta`.
+  - **selected** (`boolean`): the current value — tinted row, check mark at the right, `aria-selected="true"`.
+  - **searchText** (`string`): more text the query matches beside the label, which always matches — a path, synonyms. Defaults to `meta`.
+  - **hideWhileSearching** (`boolean`): a row that is not a thing to find (a "None" row) — shown with an empty query only.
+- **onPick** (`(id: string) => void`, required): called with the chosen item's id, and nothing else happens — close the sheet yourself.
+- **createLabel** (`(query: string) => string`): the create row's text.
+- **createMeta** (`(query: string) => string`): a muted second line under the create row — what creating does.
+- **onCreate** (`(query: string) => void`): called with the TRIMMED query. The create row is offered last when both `createLabel` and `onCreate` are given and the trimmed query matches no item label exactly (case and accents aside).
+- **emptyText** (`(query: string) => string`): shown instead of the list when nothing matches and there is no create row.
+- **foot** (`string`): the note under the list.
+- **dataTestId** (`string`, default `picker-sheet`): on the sheet's paper. Sub-elements: `${id}-search`, `${id}-item-${item.id}`, `${id}-create`, `${id}-close`, plus `${id}-check-${item.id}`, `${id}-create-meta`, `${id}-empty`, `${id}-foot`, `${id}-list`.
+
+## Behaviour
+
+- Nothing takes focus inside the sheet on open — the dialog itself does — so a phone does not raise its keyboard over the list; the selected row is scrolled into view. Tab reaches the search box.
+- Filtering is a substring match on each item's label and `searchText`, case and ACCENTS aside ("acai" finds "Açaí", as in `CategorySelect`).
+- ↑/↓ move the keyboard cursor (wrapping at both ends, as `Command` does) and Enter picks the row under it. Typing puts the cursor on the first match, so "type, then Enter" picks it — or creates, when the create row is the only row. The cursor is drawn only once an arrow key has moved it: typing alone shows no ring on a phone.
+- Esc and a tap outside close (through `onClose`).
+- The search box is a `combobox` over a `listbox`; rows are `option`s and the cursor is announced through `aria-activedescendant`.
+- Layering: both surfaces sit at `stackedOverlayZIndex` (`tokens/layers`), so a sheet opened from inside a `StackedModal` paints ABOVE it, however deep the stack.
+- Surface: under `CategorySelect`'s sheet breakpoint (480px) it is a full-width bottom sheet (radius 16 16 0 0, max-height 88%, no grab handle); above it, a centred 520px dialog (max-height 780px, radius 14).
+
+## Usage Examples
+
+### A category field
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<PickerSheet
+  open={open}
+  onClose={() => setOpen(false)}
+  kicker={copy.product}
+  title={copy.category}
+  searchPlaceholder={copy.searchCategory}
+  searchLabel={copy.searchCategory}
+  closeLabel={copy.close}
+  items={categories.map((category) => ({
+    id: category.id,
+    label: category.name,
+    meta: category.path,              // "Drinks › Juices"
+    indent: category.depth,
+    selected: category.id === value,
+  }))}
+  onPick={(id) => {
+    setValue(id);
+    setOpen(false);
+  }}
+  createLabel={(query) => copy.createCategory(query)}
+  onCreate={async (name) => {
+    const created = await createCategory(name);
+    setValue(created.id);
+    setOpen(false);
+  }}
+  foot={copy.categoryFoot}
+/>
+```
+
+### Pick only
+
+Leave out `onCreate` and give `emptyText`, so a query that matches nothing says so.
+
+```tsx
+<PickerSheet
+  open={open}
+  onClose={close}
+  title={copy.station}
+  searchPlaceholder={copy.searchStation}
+  searchLabel={copy.searchStation}
+  closeLabel={copy.close}
+  items={stations}
+  onPick={pickStation}
+  emptyText={(query) => copy.noStation(query)}
+/>
+```
+
+## Accessibility Notes
+
+- The dialog is named by `title`; on a phone the bottom sheet's paper carries `role="dialog"`, `aria-modal` and the same `aria-labelledby`.
+- Focus is contained by the modal and returns to the trigger on close.
+- Selection is `aria-selected` on the option, not colour alone — the check mark is drawn too.
+
+## Styling Notes
+
+- Sizes are the prototype's own px drawn through `rem()` (`tokens/relative`), so a density mode scales the sheet with everything else.
+- The search field takes the library's field height, border and corner (`tokens/field-height`, `tokens/field-radius`).
+- Colours are palette roles: `background.paper` for the surface, `divider` for the rules, `action.hover` on hover, `primary.main` at 0.10 for the selected row and for the check and the create row.

package/src/components/form/PickerSheet/PickerSheet.parts.tsx

@@ -0,0 +1,225 @@
+'use client';
+
+import Box from '@mui/material/Box/index.js';
+import InputBase from '@mui/material/InputBase/index.js';
+
+import { CheckGlyph, SearchGlyph } from '../CategorySelect/CategoryIcons';
+import type { PickerSheetView } from './picker-sheet-model';
+import {
+  checkSx,
+  closeButtonSx,
+  createLabelSx,
+  emptySx,
+  headSx,
+  kickerSx,
+  listSx,
+  rowLabelSx,
+  rowMetaSx,
+  rowPaddingLeft,
+  rowSx,
+  rowTextSx,
+  searchFieldSx,
+  titleSx,
+} from './PickerSheet.styles';
+import type { PickerSheetItem } from './PickerSheet.types';
+
+/** The close button's cross, at the weight of the search glyph under it. */
+function CloseGlyph(): React.JSX.Element {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      aria-hidden="true"
+    >
+      <path d="M18 6 6 18M6 6l12 12" />
+    </svg>
+  );
+}
+
+interface HeadProps {
+  kicker?: string;
+  title: string;
+  titleId: string;
+  closeLabel: string;
+  onClose: () => void;
+  dataTestId: string;
+}
+
+/** `.sh` — kicker over title, and the bordered close button. */
+export function PickerSheetHead({ kicker, title, titleId, closeLabel, onClose, dataTestId }: HeadProps): React.JSX.Element {
+  return (
+    <Box sx={headSx}>
+      <Box sx={{ flex: '1 1 auto', minWidth: 0 }}>
+        {kicker ? <Box sx={kickerSx}>{kicker}</Box> : null}
+        <Box component="h2" id={titleId} sx={titleSx}>
+          {title}
+        </Box>
+      </Box>
+      <Box
+        component="button"
+        type="button"
+        aria-label={closeLabel}
+        data-testid={`${dataTestId}-close`}
+        onClick={onClose}
+        sx={closeButtonSx}
+      >
+        <CloseGlyph />
+      </Box>
+    </Box>
+  );
+}
+
+interface SearchProps {
+  query: string;
+  placeholder: string;
+  label: string;
+  listId: string;
+  activeId: string | undefined;
+  /** False when the list shows no row — then there is no listbox to point at. */
+  expanded: boolean;
+  inputRef: React.RefObject<HTMLInputElement | null>;
+  onQueryChange: (next: string) => void;
+  onKeyDown: (event: React.KeyboardEvent) => void;
+  dataTestId: string;
+}
+
+/** The search field — a combobox over the list below it, so the cursor is announced. */
+export function PickerSheetSearch(props: SearchProps): React.JSX.Element {
+  const { query, placeholder, label, listId, activeId, expanded, inputRef, onQueryChange, onKeyDown, dataTestId } = props;
+  return (
+    <Box sx={searchFieldSx}>
+      <SearchGlyph />
+      <InputBase
+        inputRef={inputRef}
+        value={query}
+        placeholder={placeholder}
+        autoComplete="off"
+        sx={{ width: '100%' }}
+        onChange={(event) => onQueryChange(event.target.value)}
+        onKeyDown={onKeyDown}
+        inputProps={{
+          role: 'combobox',
+          'aria-label': label,
+          'aria-expanded': expanded,
+          'aria-controls': expanded ? listId : undefined,
+          'aria-autocomplete': 'list',
+          'aria-activedescendant': activeId,
+          'data-testid': `${dataTestId}-search`,
+        }}
+      />
+    </Box>
+  );
+}
+
+interface RowProps {
+  item: PickerSheetItem;
+  rowId: string;
+  active: boolean;
+  /** False while searching: the tree flattens and `meta` carries the path. */
+  indented: boolean;
+  onChoose: () => void;
+  dataTestId: string;
+}
+
+/** `.pitem` — one item: label, optional meta line, and the check when selected. */
+function PickerSheetRow({ item, rowId, active, indented, onChoose, dataTestId }: RowProps): React.JSX.Element {
+  const selected = item.selected ?? false;
+  const depth = indented ? (item.indent ?? 0) : 0;
+  return (
+    <Box
+      component="li"
+      id={rowId}
+      role="option"
+      aria-selected={selected}
+      data-testid={`${dataTestId}-item-${item.id}`}
+      onClick={onChoose}
+      sx={(theme) => ({ ...rowSx(theme, selected, active), paddingLeft: rowPaddingLeft(theme, depth) })}
+    >
+      <Box component="span" sx={rowTextSx}>
+        <Box component="span" sx={rowLabelSx}>
+          {item.label}
+        </Box>
+        {item.meta ? (
+          <Box component="span" sx={rowMetaSx}>
+            {item.meta}
+          </Box>
+        ) : null}
+      </Box>
+      {selected ? (
+        <Box component="span" sx={checkSx} data-testid={`${dataTestId}-check-${item.id}`}>
+          <CheckGlyph />
+        </Box>
+      ) : null}
+    </Box>
+  );
+}
+
+interface ListProps {
+  view: PickerSheetView;
+  activeIndex: number;
+  /** Draw the cursor's ring (an arrow key moved it) — `activeIndex` alone only feeds the screen reader. */
+  cursorShown: boolean;
+  listId: string;
+  rowId: (index: number) => string;
+  listRef: React.RefObject<HTMLUListElement | null>;
+  createLabel?: (query: string) => string;
+  createMeta?: (query: string) => string;
+  emptyText?: (query: string) => string;
+  onChoose: (index: number) => void;
+  dataTestId: string;
+}
+
+/** The matching items, then the create row — or the empty text when there is neither. */
+export function PickerSheetList(props: ListProps): React.JSX.Element | null {
+  const { view, listId, rowId, listRef, createLabel, createMeta, emptyText, onChoose, dataTestId } = props;
+  const drawn = props.cursorShown ? props.activeIndex : -1;
+  if (view.rowCount === 0) {
+    const text = emptyText?.(view.query);
+    return text ? (
+      <Box sx={emptySx} role="status" data-testid={`${dataTestId}-empty`}>
+        {text}
+      </Box>
+    ) : null;
+  }
+  const createIndex = view.items.length;
+  return (
+    <Box component="ul" id={listId} role="listbox" ref={listRef} sx={listSx} data-testid={`${dataTestId}-list`}>
+      {view.items.map((item, index) => (
+        <PickerSheetRow
+          key={item.id}
+          item={item}
+          rowId={rowId(index)}
+          active={index === drawn}
+          indented={view.query.length === 0}
+          onChoose={() => onChoose(index)}
+          dataTestId={dataTestId}
+        />
+      ))}
+      {view.canCreate && createLabel ? (
+        <Box
+          component="li"
+          id={rowId(createIndex)}
+          role="option"
+          aria-selected={false}
+          data-testid={`${dataTestId}-create`}
+          onClick={() => onChoose(createIndex)}
+          sx={(theme) => rowSx(theme, false, drawn === createIndex)}
+        >
+          <Box component="span" sx={rowTextSx}>
+            <Box component="span" sx={createLabelSx}>
+              {createLabel(view.query)}
+            </Box>
+            {createMeta ? (
+              <Box component="span" sx={rowMetaSx} data-testid={`${dataTestId}-create-meta`}>
+                {createMeta(view.query)}
+              </Box>
+            ) : null}
+          </Box>
+        </Box>
+      ) : null}
+    </Box>
+  );
+}