@charcuterie/ui 3.0.0 → 3.2.0

package/src/Overlay/OverlayPanel.tsx

@@ -10,7 +10,7 @@ import {
   useInteractions,
   useRole,
 } from "@floating-ui/react"
-import type { ReactNode } from "react"
+import type { ReactNode, RefObject } from "react"
 import { useCallback, useEffect } from "react"
 
 import { lockScrollBehind } from "./lockScrollBehind.ts"
@@ -58,6 +58,17 @@ export type OverlayPanelProps = {
   "aria-labelledby"?: string
   children: ReactNode
   className?: string
+  /**
+   * Which element takes the caret when the panel opens.
+   *
+   * Without it the focus manager takes the first tabbable element,
+   * which for anything with chrome is the **Close button** — so a
+   * panel wrapping a form opens with the caret on "Close" and the
+   * first thing typed goes nowhere. A consumer cannot fix that from
+   * outside: focusing in its own effect races the manager, and the
+   * manager wins, which reads as the app ignoring you.
+   */
+  initialFocus?: RefObject<HTMLElement | null>
   /** Escape and an outside press both close. */
   isDismissable?: boolean
   isVisible: boolean
@@ -70,6 +81,7 @@ export const OverlayPanel = ({
   "aria-labelledby": ariaLabelledBy,
   children,
   className,
+  initialFocus,
   isDismissable = true,
   isVisible,
   onClose,
@@ -160,6 +172,10 @@ export const OverlayPanel = ({
         <div className="fixed inset-0 z-[var(--layer-modal)] flex items-center justify-center">
           <FloatingFocusManager
             context={context}
+            // `undefined` keeps the manager's own default (the first
+            // tabbable), so nothing changes for a panel that does not
+            // ask.
+            initialFocus={initialFocus ?? undefined}
             // Only the top traps focus; a lower panel is `inert`
             // anyway, and two live traps fight over one caret.
             disabled={!isTop}

package/src/argTypes.storyHelpers.ts

@@ -1,4 +1,8 @@
 import { connectionTransitions } from "@charcuterie/logic"
+import {
+  CATEGORICAL_HUES,
+  CATEGORICAL_INDEXES,
+} from "@charcuterie/tokens"
 import type { InputType } from "storybook/internal/types"
 
 import { CONTROL_SIZE_CLASS } from "./controlStyles.ts"
@@ -95,6 +99,41 @@ export const PLACEMENT_OPTIONS = [
 
 export const intentArgType = toChoiceArgType(INTENT_OPTIONS)
 
+/**
+ * `categorical` is the one enumerable prop in the package whose
+ * values are **numbers**, so it cannot go through `toOptions` —
+ * `Object.keys` on a numerically-keyed record returns
+ * `["1", "2", …]`, and a control handing the component `"3"` where
+ * it wants `3` indexes a `Record<CategoricalIndex, …>` with a
+ * string and paints nothing. Reading `CATEGORICAL_INDEXES` keeps
+ * the type and the control agreeing.
+ *
+ * `undefined` leads the list because it is the real default: a
+ * badge with no `categorical` is an `intent` badge, and a control
+ * with no way back to that would make the two props look like a
+ * choice the reader cannot undo.
+ */
+export const CATEGORICAL_OPTIONS = [...CATEGORICAL_INDEXES]
+
+export const categoricalArgType: InputType = {
+  control: { type: "select" },
+  options: [undefined, ...CATEGORICAL_OPTIONS],
+  // The names are `CATEGORICAL_HUES`', not invented here — a picker
+  // that says "3" tells a reader nothing, and `Swatch` already
+  // settled that a colour needs a word attached.
+  mapping: Object.fromEntries(
+    CATEGORICAL_OPTIONS.map((index) => [index, index]),
+  ),
+  table: {
+    type: {
+      summary: CATEGORICAL_OPTIONS.map(
+        (index) =>
+          `${index} (${CATEGORICAL_HUES[index].label})`,
+      ).join(" | "),
+    },
+  },
+}
+
 export const controlSizeArgType = toChoiceArgType(
   CONTROL_SIZE_OPTIONS,
 )

package/src/categoricalStyles.ts

@@ -0,0 +1,244 @@
+/**
+ * One categorical index → class map, the twin of
+ * `intentStyles.ts`.
+ *
+ * Its own file rather than ten more entries in that one, because
+ * the two families are keyed by different things and mean different
+ * things. `intentStyles.ts` opens by explaining that it exists to
+ * delete rip-deck's duplicated `TONE_CLASS` — a *status* map, where
+ * every key is a claim about state. Nothing here is a claim about
+ * anything: an index is a user's pick for a label, and the only
+ * thing a component may do with it is paint it. Keeping them apart
+ * is also what keeps `IntentName` an exhaustive union that
+ * `getAsyncIntent` can switch over.
+ *
+ * **Every class name is written out in full, and that is not
+ * negotiable.** Tailwind v4 scans source text for *complete* class
+ * strings, so `` `bg-categorical-${index}-solid` `` generates
+ * nothing at all — the badge renders unstyled with no error, no
+ * warning, and no failing test unless something checks. Something
+ * does: `tailwindCandidates.test.ts` compiles every literal in this
+ * package through the real Tailwind and fails on any candidate it
+ * cannot generate. Forty lines of near-duplication is the price,
+ * and the alternative is the `--color-danger-9` that shipped in
+ * Docket: a token name that had never existed, resolving to
+ * nothing, painting transparent, and passing every assertion about
+ * whether the element was rendered.
+ */
+
+import type { CategoricalIndex } from "@charcuterie/tokens"
+
+import type { IntentAppearance } from "./intentStyles.ts"
+
+export const CATEGORICAL_APPEARANCE_CLASS: Record<
+  CategoricalIndex,
+  Record<IntentAppearance, string>
+> = {
+  1: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-1-content",
+    outline:
+      "border-categorical-1-border bg-transparent text-categorical-1-content",
+    soft: "border-categorical-1-border bg-categorical-1-surface text-categorical-1-content",
+    solid:
+      "border-transparent bg-categorical-1-solid text-categorical-1-on-solid",
+  },
+  2: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-2-content",
+    outline:
+      "border-categorical-2-border bg-transparent text-categorical-2-content",
+    soft: "border-categorical-2-border bg-categorical-2-surface text-categorical-2-content",
+    solid:
+      "border-transparent bg-categorical-2-solid text-categorical-2-on-solid",
+  },
+  3: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-3-content",
+    outline:
+      "border-categorical-3-border bg-transparent text-categorical-3-content",
+    soft: "border-categorical-3-border bg-categorical-3-surface text-categorical-3-content",
+    solid:
+      "border-transparent bg-categorical-3-solid text-categorical-3-on-solid",
+  },
+  4: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-4-content",
+    outline:
+      "border-categorical-4-border bg-transparent text-categorical-4-content",
+    soft: "border-categorical-4-border bg-categorical-4-surface text-categorical-4-content",
+    solid:
+      "border-transparent bg-categorical-4-solid text-categorical-4-on-solid",
+  },
+  5: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-5-content",
+    outline:
+      "border-categorical-5-border bg-transparent text-categorical-5-content",
+    soft: "border-categorical-5-border bg-categorical-5-surface text-categorical-5-content",
+    solid:
+      "border-transparent bg-categorical-5-solid text-categorical-5-on-solid",
+  },
+  6: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-6-content",
+    outline:
+      "border-categorical-6-border bg-transparent text-categorical-6-content",
+    soft: "border-categorical-6-border bg-categorical-6-surface text-categorical-6-content",
+    solid:
+      "border-transparent bg-categorical-6-solid text-categorical-6-on-solid",
+  },
+  7: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-7-content",
+    outline:
+      "border-categorical-7-border bg-transparent text-categorical-7-content",
+    soft: "border-categorical-7-border bg-categorical-7-surface text-categorical-7-content",
+    solid:
+      "border-transparent bg-categorical-7-solid text-categorical-7-on-solid",
+  },
+  8: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-8-content",
+    outline:
+      "border-categorical-8-border bg-transparent text-categorical-8-content",
+    soft: "border-categorical-8-border bg-categorical-8-surface text-categorical-8-content",
+    solid:
+      "border-transparent bg-categorical-8-solid text-categorical-8-on-solid",
+  },
+  9: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-9-content",
+    outline:
+      "border-categorical-9-border bg-transparent text-categorical-9-content",
+    soft: "border-categorical-9-border bg-categorical-9-surface text-categorical-9-content",
+    solid:
+      "border-transparent bg-categorical-9-solid text-categorical-9-on-solid",
+  },
+  10: {
+    ghost:
+      "border-transparent bg-transparent text-categorical-10-content",
+    outline:
+      "border-categorical-10-border bg-transparent text-categorical-10-content",
+    soft: "border-categorical-10-border bg-categorical-10-surface text-categorical-10-content",
+    solid:
+      "border-transparent bg-categorical-10-solid text-categorical-10-on-solid",
+  },
+}
+
+/**
+ * Hover, split out for exactly the reason `INTENT_HOVER_CLASS` is:
+ * most things wearing a colour are not interactive. A label pill in
+ * a task list that lightens under the cursor is telling the user it
+ * can be clicked, and a `Badge` cannot be. So an interactive
+ * component opts in, and a static one cannot accidentally opt in.
+ *
+ * `solid` hovers toward `solidHover`, which for this family is
+ * **brighter** rather than deeper — the fill carries a near-black
+ * label, so it moves away from it in the opposite direction to an
+ * intent's white-labelled fill.
+ */
+export const CATEGORICAL_HOVER_CLASS: Record<
+  CategoricalIndex,
+  Record<IntentAppearance, string>
+> = {
+  1: {
+    ghost: "hover:bg-categorical-1-surface",
+    outline: "hover:bg-categorical-1-surface",
+    soft: "hover:bg-categorical-1-surface-hover",
+    solid: "hover:bg-categorical-1-solid-hover",
+  },
+  2: {
+    ghost: "hover:bg-categorical-2-surface",
+    outline: "hover:bg-categorical-2-surface",
+    soft: "hover:bg-categorical-2-surface-hover",
+    solid: "hover:bg-categorical-2-solid-hover",
+  },
+  3: {
+    ghost: "hover:bg-categorical-3-surface",
+    outline: "hover:bg-categorical-3-surface",
+    soft: "hover:bg-categorical-3-surface-hover",
+    solid: "hover:bg-categorical-3-solid-hover",
+  },
+  4: {
+    ghost: "hover:bg-categorical-4-surface",
+    outline: "hover:bg-categorical-4-surface",
+    soft: "hover:bg-categorical-4-surface-hover",
+    solid: "hover:bg-categorical-4-solid-hover",
+  },
+  5: {
+    ghost: "hover:bg-categorical-5-surface",
+    outline: "hover:bg-categorical-5-surface",
+    soft: "hover:bg-categorical-5-surface-hover",
+    solid: "hover:bg-categorical-5-solid-hover",
+  },
+  6: {
+    ghost: "hover:bg-categorical-6-surface",
+    outline: "hover:bg-categorical-6-surface",
+    soft: "hover:bg-categorical-6-surface-hover",
+    solid: "hover:bg-categorical-6-solid-hover",
+  },
+  7: {
+    ghost: "hover:bg-categorical-7-surface",
+    outline: "hover:bg-categorical-7-surface",
+    soft: "hover:bg-categorical-7-surface-hover",
+    solid: "hover:bg-categorical-7-solid-hover",
+  },
+  8: {
+    ghost: "hover:bg-categorical-8-surface",
+    outline: "hover:bg-categorical-8-surface",
+    soft: "hover:bg-categorical-8-surface-hover",
+    solid: "hover:bg-categorical-8-solid-hover",
+  },
+  9: {
+    ghost: "hover:bg-categorical-9-surface",
+    outline: "hover:bg-categorical-9-surface",
+    soft: "hover:bg-categorical-9-surface-hover",
+    solid: "hover:bg-categorical-9-solid-hover",
+  },
+  10: {
+    ghost: "hover:bg-categorical-10-surface",
+    outline: "hover:bg-categorical-10-surface",
+    soft: "hover:bg-categorical-10-surface-hover",
+    solid: "hover:bg-categorical-10-solid-hover",
+  },
+}
+
+/**
+ * The fill on its own, for the parts of a component that are a dot
+ * or a bar rather than a box — the swatch beside a label in a
+ * picker, a series marker on a chart. Same values, no border and no
+ * hover, because neither of those is a surface anyone can point at.
+ */
+export const CATEGORICAL_SOLID_FILL_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "bg-categorical-1-solid",
+  2: "bg-categorical-2-solid",
+  3: "bg-categorical-3-solid",
+  4: "bg-categorical-4-solid",
+  5: "bg-categorical-5-solid",
+  6: "bg-categorical-6-solid",
+  7: "bg-categorical-7-solid",
+  8: "bg-categorical-8-solid",
+  9: "bg-categorical-9-solid",
+  10: "bg-categorical-10-solid",
+}
+
+/** The same ten as text, for a glyph or a dot's ring. */
+export const CATEGORICAL_CONTENT_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "text-categorical-1-content",
+  2: "text-categorical-2-content",
+  3: "text-categorical-3-content",
+  4: "text-categorical-4-content",
+  5: "text-categorical-5-content",
+  6: "text-categorical-6-content",
+  7: "text-categorical-7-content",
+  8: "text-categorical-8-content",
+  9: "text-categorical-9-content",
+  10: "text-categorical-10-content",
+}

package/src/index.ts

@@ -65,6 +65,26 @@ export type {
 export { Alert } from "./Alert/Alert.tsx"
 export type { BadgeProps } from "./Badge/Badge.tsx"
 export { Badge } from "./Badge/Badge.tsx"
+export type {
+  BoardMove,
+  BoardProps,
+} from "./Board/Board.tsx"
+export { Board } from "./Board/Board.tsx"
+export type { BoardItem } from "./Board/BoardCard.tsx"
+export type { BoardLane } from "./Board/BoardLaneList.tsx"
+export type {
+  BoardDropLane,
+  BoardDropTarget,
+  BoardPoint,
+  BoardRect,
+} from "./Board/boardMove.ts"
+export {
+  chooseDropIndex,
+  chooseDropTarget,
+  describeMove,
+  getIsMoveMeaningful,
+  toSettledIndex,
+} from "./Board/boardMove.ts"
 export type { ButtonProps } from "./Button/Button.tsx"
 export { Button } from "./Button/Button.tsx"
 export type { ButtonLinkProps } from "./ButtonLink/ButtonLink.tsx"
@@ -86,6 +106,12 @@ export type {
 export { ColorSchemeToggle } from "./ColorSchemeToggle/ColorSchemeToggle.tsx"
 export type { ComboboxProps } from "./Combobox/Combobox.tsx"
 export { Combobox } from "./Combobox/Combobox.tsx"
+export {
+  CATEGORICAL_APPEARANCE_CLASS,
+  CATEGORICAL_CONTENT_CLASS,
+  CATEGORICAL_HOVER_CLASS,
+  CATEGORICAL_SOLID_FILL_CLASS,
+} from "./categoricalStyles.ts"
 export type { BadgeSize } from "./controlStyles.ts"
 export {
   BADGE_SIZE_CLASS,
@@ -97,6 +123,53 @@ export {
   MIN_TOUCH_TARGET_CLASS,
   SPINNER_SIZE_CLASS,
 } from "./controlStyles.ts"
+export type {
+  DataTableColumn,
+  DataTableProps,
+  DataTableSelection,
+  DataTableSort,
+} from "./DataTable/DataTable.tsx"
+export { DataTable } from "./DataTable/DataTable.tsx"
+export type { DatePickerProps } from "./DatePicker/DatePicker.tsx"
+export { DatePicker } from "./DatePicker/DatePicker.tsx"
+export type { DatePreset } from "./DatePicker/datePresets.ts"
+export { DEFAULT_DATE_PRESETS } from "./DatePicker/datePresets.ts"
+export type {
+  DateInputKeywords,
+  DateInputResult,
+  ParseDateInputOptions,
+} from "./DatePicker/parseDateInput.ts"
+export {
+  DEFAULT_DATE_INPUT_KEYWORDS,
+  parseDateInput,
+} from "./DatePicker/parseDateInput.ts"
+export type {
+  DateRange,
+  PlainDate,
+  PlainDateFormatOptions,
+} from "./DatePicker/plainDate.ts"
+export {
+  addDays,
+  addMonths,
+  clampPlainDate,
+  comparePlainDates,
+  formatPlainDate,
+  getDayNumber,
+  getDaysBetween,
+  getDaysInMonth,
+  getFirstDayOfWeek,
+  getIsLeapYear,
+  getIsSameDay,
+  getIsValidPlainDate,
+  getIsWithinRange,
+  getLocalPlainDate,
+  getMonthNames,
+  getPlainDateFromDayNumber,
+  getWeekday,
+  getWeekdayNames,
+  parseIsoDate,
+  toIsoDate,
+} from "./DatePicker/plainDate.ts"
 export type {
   DialogProps,
   DialogSize,
@@ -146,6 +219,22 @@ export type {
 export { LogViewer } from "./LogViewer/LogViewer.tsx"
 export type { MainProps } from "./Main/Main.tsx"
 export { Main } from "./Main/Main.tsx"
+export type {
+  MarkdownEditorProps,
+  MarkdownImageUpload,
+} from "./MarkdownEditor/MarkdownEditor.tsx"
+export { MarkdownEditor } from "./MarkdownEditor/MarkdownEditor.tsx"
+export { toMarkdownImage } from "./MarkdownEditor/markdownCommands.ts"
+export type {
+  MarkdownLine,
+  MarkdownLineKind,
+  MarkdownSpan,
+  MarkdownSpanKind,
+} from "./MarkdownEditor/markdownSpans.ts"
+export {
+  toLineIndex,
+  toMarkdownLines,
+} from "./MarkdownEditor/markdownSpans.ts"
 export type {
   MediaTileProps,
   MediaTileRatio,

package/src/sourceRules.test.ts

@@ -211,9 +211,30 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
   // inside it.
   expect(containerComponents).toEqual([
     "Alert",
+    // `Board` declares **two** containers and neither is the element
+    // that queries it: the board's own box decides how many lanes are
+    // on screen, and each lane's list — in `BoardLaneList.tsx`, which
+    // is a member rather than a component by the `<Name>/<Name>.tsx`
+    // rule — decides what shape a card is. Only the first of those is
+    // in this list, and that is enough: it is `<Board` a story renders,
+    // so `<Board` is what a shrink-to-fit `StoryCell` would collapse.
+    "Board",
     "Card",
+    // `DataTable` joins them as the first component whose *layout*
+    // is the container query rather than its padding: below `--cq-md`
+    // a row stops being a row and becomes a labelled block, so the
+    // whole point of the component is a query it declares itself.
+    "DataTable",
+    // `DatePicker`'s panel is the container, and it is the first one
+    // here whose container is *not* the element a caller sized. A
+    // portalled panel is clamped to the space floating-ui found for
+    // it, so the calendar reads that and not the window — which is
+    // the case a media query cannot express at all, and the case the
+    // owner is in whenever he browses zoomed in.
+    "DatePicker",
     "EmptyState",
     "Main",
+    "MarkdownEditor",
     "MediaTile",
   ])
 
@@ -374,12 +395,42 @@ test("the barrel is the only place components are re-exported", async () => {
   // the barrel by the `<Name>/<Name>.tsx` rule, exactly as
   // `SegmentedOption` and `ListboxOption` do.
   //
+  // `MarkdownEditor` — Docket's live hybrid editor, a real
+  // `<textarea>` with a painted layer behind it — is +1 -> 46. Its
+  // `markdownSpans.ts` and `markdownCommands.ts` are pure modules
+  // rather than components and stay out of this count by the
+  // `<Name>/<Name>.tsx` rule.
+  //
   // `Picker` — a `Listbox` with its trigger already attached — is +1 ->
   // 45. It is a component rather than a recipe in the docs because the
   // fleet wrote it four separate times (plex-channels' `SelectListbox`,
   // board-games' `SelectMenu`, mux-magic's `ListboxPicker`, and twice
   // inside this package), each with its own hand-rolled chevron.
-  expect(componentNames.length).toBe(45)
+  // `DatePicker` — a typed date field with a calendar dialog — is +1
+  // -> 47. `DateGrid.tsx`, `plainDate.ts` and `parseDateInput.ts` are
+  // its members and stay out of this count by the `<Name>/<Name>.tsx`
+  // rule, exactly as `SegmentedOption` and `ListboxOption` do. The
+  // two `.ts` ones are still exported from the barrel: the calendar
+  // arithmetic and the input grammar are the parts a consumer needs
+  // *outside* the field (Docket counts staleness in days), and they
+  // reach nothing but `Intl`.
+  //
+  // `DataTable` — the reflowing table Docket's task lists, backlog and
+  // search results need — is +1 -> 48. It **composes**
+  // `SortableTableHeader` rather than subsuming it: that component is
+  // already in a published 1.0.0 with a consumer of its own, so
+  // removing it would be a breaking change bought for nothing, and
+  // both stay in this count.
+  //
+  // `Board` — lanes of cards, sized by their container and moved by
+  // keyboard or by pointer — is +1 -> 49. It is the library's first
+  // component whose own operation is a **write** rather than a
+  // selection, and the first to declare two nested containers.
+  // `BoardCard.tsx`, `BoardLaneList.tsx`, `boardMove.ts` and
+  // `useBoardDrag.ts` are its members and stay out of this count and
+  // the barrel by the `<Name>/<Name>.tsx` rule, exactly as
+  // `ToolbarSlot` and `QueryBuilderRow` do.
+  expect(componentNames.length).toBe(49)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)