@12-apps/ui 1.23.0 → 2.1.0

package/src/components/navigation/NavigationMenu/NavigationMenu.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { ReactNode } from 'react';
 
 export interface NavigationMenuItem {
@@ -76,12 +77,16 @@ export interface NavigationMenuProps {
   /**
    * Color scheme of the menu
    */
-  color?: 'default' | 'primary' | 'secondary';
+  /**
+   * `neutral` is what this called `default`: the unaccented state, renamed to
+   * the house word rather than kept as a third spelling of the same idea.
+   */
+  color?: Extract<ColorValue, 'primary' | 'secondary' | 'neutral'>;
 
   /**
    * Size of the menu items
    */
-  size?: 'sm' | 'md' | 'lg';
+  size?: Extract<SizeValue, 'sm' | 'md' | 'lg'>;
 
   /**
    * Minimal style with no borders, shadows, or container backgrounds

package/src/components/navigation/Pagination/Pagination.tsx

@@ -139,7 +139,9 @@ const PaginationControl: React.FC<
       showFirstButton={p.showFirstButton && !isDots}
       showLastButton={p.showLastButton && !isDots}
       disabled={p.disabled}
-      color={p.color}
+      // MUI spells the unaccented pagination colour `standard`; ours is
+      // `neutral`, translated here rather than carried as a second name.
+      color={p.color === undefined ? undefined : p.color === 'neutral' ? 'standard' : p.color}
       renderItem={renderItem}
       {...rest}
     />

package/src/components/navigation/Pagination/Pagination.types.ts

@@ -1,7 +1,8 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { PaginationProps as MuiPaginationProps } from '@mui/material';
 import type { ReactNode } from 'react';
 
-export interface PaginationProps extends Omit<MuiPaginationProps, 'variant' | 'size'> {
+export interface PaginationProps extends Omit<MuiPaginationProps, 'variant' | 'size' | 'color'> {
   /**
    * The variant of the pagination
    */
@@ -10,7 +11,7 @@ export interface PaginationProps extends Omit<MuiPaginationProps, 'variant' | 's
   /**
    * Size of the pagination buttons
    */
-  size?: 'sm' | 'md' | 'lg';
+  size?: Extract<SizeValue, 'sm' | 'md' | 'lg'>;
   
   /**
    * Current page number
@@ -85,7 +86,8 @@ export interface PaginationProps extends Omit<MuiPaginationProps, 'variant' | 's
   /**
    * Custom color for the active page
    */
-  color?: 'primary' | 'secondary' | 'standard';
+  /** `neutral` is what MUI spells `standard`; it is translated at the boundary. */
+  color?: Extract<ColorValue, 'primary' | 'secondary' | 'neutral'>;
   
   /**
    * Whether to show page info text

package/src/components/navigation/Tabs/Tabs.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { TabsProps as MuiTabsProps } from '@mui/material';
 import type { ReactNode } from 'react';
 
@@ -57,7 +58,7 @@ export interface TabsProps extends Omit<MuiTabsProps, 'variant' | 'children' | '
   /**
    * Size of the tabs
    */
-  size?: 'sm' | 'md' | 'lg';
+  size?: Extract<SizeValue, 'sm' | 'md' | 'lg'>;
   
   /**
    * Array of tab items
@@ -77,7 +78,7 @@ export interface TabsProps extends Omit<MuiTabsProps, 'variant' | 'children' | '
   /**
    * Color theme for the tabs
    */
-  color?: 'primary' | 'secondary';
+  color?: Extract<ColorValue, 'primary' | 'secondary'>;
   
   /**
    * Whether tabs should fill the full width

package/src/components/typography/Blockquote/Blockquote.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue } from '../../../tokens/scales';
 import type React from 'react';
 
 export type BlockquoteVariant = 'default' | 'bordered' | 'citation';
@@ -6,6 +7,6 @@ export interface BlockquoteProps extends React.HTMLAttributes<HTMLElement> {
   variant?: BlockquoteVariant;
   author?: string;
   source?: string;
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+  color?: Exclude<ColorValue, 'info'>;
   children: React.ReactNode;
 }

package/src/components/typography/Code/Code.types.ts

@@ -1,3 +1,4 @@
+import type { SizeValue } from '../../../tokens/scales';
 import type React from 'react';
 
 export type CodeVariant = 'inline' | 'block' | 'highlight';
@@ -7,6 +8,6 @@ export interface CodeProps extends React.HTMLAttributes<HTMLElement> {
   language?: string;
   copyable?: boolean;
   lineNumbers?: boolean;
-  size?: 'xs' | 'sm' | 'md' | 'lg';
+  size?: Extract<SizeValue, 'xs' | 'sm' | 'md' | 'lg'>;
   children: React.ReactNode;
 }

package/src/components/typography/Heading/Heading.types.ts

@@ -1,10 +1,11 @@
+import type { ColorValue } from '../../../tokens/scales';
 import type React from 'react';
 
 export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display';
 
 export interface HeadingProps extends React.HTMLAttributes<globalThis.HTMLHeadingElement> {
   level?: HeadingLevel;
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+  color?: Exclude<ColorValue, 'info'>;
   weight?: 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
   gradient?: boolean;
   children: React.ReactNode;

package/src/components/typography/Paragraph/Paragraph.types.ts

@@ -1,10 +1,11 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type React from 'react';
 
 export type ParagraphVariant = 'default' | 'lead' | 'muted' | 'small';
 
 export interface ParagraphProps extends React.HTMLAttributes<globalThis.HTMLParagraphElement> {
   variant?: ParagraphVariant;
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  color?: Exclude<ColorValue, 'info'>;
+  size?: SizeValue;
   children: React.ReactNode;
 }

package/src/components/typography/Text/Text.types.ts

@@ -1,11 +1,12 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type React from 'react';
 
 export type TextVariant = 'body' | 'heading' | 'caption' | 'code';
 
 export interface TextProps extends React.HTMLAttributes<HTMLSpanElement> {
   variant?: TextVariant;
-  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  color?: Exclude<ColorValue, 'info'>;
+  size?: SizeValue;
   weight?: 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
   as?: keyof React.JSX.IntrinsicElements;
   italic?: boolean;

package/src/components/utility/AnimatedIcon/AnimatedIcon.types.ts

@@ -1,3 +1,4 @@
+import type { SizeValue } from '../../../tokens/scales';
 import type React from 'react';
 
 export type AnimationVariant =
@@ -19,7 +20,7 @@ export type AnimationVariant =
   | 'neonFlicker'
   | 'breathe';
 
-export type AnimationSize = 'sm' | 'md' | 'lg' | 'xl';
+export type AnimationSize = Extract<SizeValue, 'sm' | 'md' | 'lg' | 'xl'>;
 
 export type ShadowStyle = 'soft' | 'hard' | 'elevated' | 'none';
 

package/src/components/utility/Overflow/index.ts

@@ -0,0 +1,6 @@
+export {
+  splitToFit,
+  useMeasuredWidth,
+  type FitRequest,
+  type FitResult,
+} from "./overflow";

package/src/components/utility/Overflow/overflow.ts

@@ -0,0 +1,125 @@
+"use client";
+
+import { useEffect, useRef, useState, type RefObject } from "react";
+
+/**
+ * MEASURE A ROW, THEN DECIDE WHAT FITS — the two pieces every "…and the rest
+ * goes in the menu" cluster needs, and the only two that are not specific to
+ * what is being collapsed.
+ *
+ * It was extracted from `DataViews`' filter toolbar (`data-views-overflow`),
+ * which still owns everything filter-shaped about that bar: what a pill costs,
+ * that an APPLIED filter ranks ahead of an idle one, and the ladder that
+ * strips the search and the counter. None of that generalises. What does is
+ * the pair below — observe a container's width, and greedily keep what fits —
+ * and a second copy of a resize-measurement loop is exactly the kind of thing
+ * that drifts silently from the first.
+ *
+ * Both are presentation only: nothing here removes an action, changes a
+ * handler, or decides that something should not be reachable. What does not
+ * fit is meant to be rendered SOMEWHERE ELSE by the caller — a menu, a panel —
+ * never dropped.
+ */
+
+/**
+ * Observe an element's content width. `0` until the first measurement lands.
+ *
+ * Zero is a meaningful answer, not a missing one: an SSR pass and a jsdom test
+ * both have no `ResizeObserver`, and the callers here read `0` as "degrade
+ * nothing" — keep every control inline. That is the honest fallback, because
+ * the alternative hides controls behind a trigger that the same environment
+ * cannot show either.
+ */
+export function useMeasuredWidth<T extends HTMLElement = HTMLDivElement>(): {
+  ref: RefObject<T | null>;
+  width: number;
+} {
+  const ref = useRef<T | null>(null);
+  const [width, setWidth] = useState(0);
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) setWidth(entry.contentRect.width);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  return { ref, width };
+}
+
+/** What one split costs the row, so a caller can price whatever comes next. */
+export interface FitResult<Item> {
+  /** Rendered on the row, in the order they were DECLARED. */
+  inline: Item[];
+  /** Everything that had no room, also in declared order. */
+  overflow: Item[];
+  /** Width the surviving items occupy, including the overflow trigger. */
+  used: number;
+}
+
+export interface FitRequest<Item> {
+  /** Rendered width of one item, however the caller prices it. */
+  widthOf: (item: Item) => number;
+  /** Stable identity — the split is decided as a set, then re-ordered. */
+  keyOf: (item: Item) => string;
+  /** The gap between two items, charged once per item kept. */
+  gap: number;
+  /** Room the items have to share, with fixed furniture already subtracted. */
+  available: number;
+  /**
+   * What the overflow trigger costs — charged ONLY when something overflows,
+   * because a row where everything fits renders no trigger at all.
+   */
+  overflowCost: number;
+  /**
+   * The order in which items claim the visible slots. Defaults to the declared
+   * order; pass a re-ordering to rank some items ahead of others.
+   *
+   * Ranking is not exempting. A high-ranked item still overflows once even the
+   * first slots run out, which is what stops a row of "important" items from
+   * claiming more width than it has and painting past its own edge.
+   */
+  priority?: readonly Item[];
+}
+
+/**
+ * Keep what fits, shed the rest — ONE AT A TIME, never all at once.
+ *
+ * The all-or-nothing version throws away room that was there: with four items
+ * and space for three, hiding all four leaves the row emptier than it needed
+ * to be.
+ *
+ * Items claim slots in `priority` order but are RENDERED in declared order:
+ * which ones are visible may change with the width, and that is the point —
+ * but the ones that stay must not reshuffle under the pointer.
+ */
+export function splitToFit<Item>(
+  items: readonly Item[],
+  request: FitRequest<Item>,
+): FitResult<Item> {
+  const { widthOf, keyOf, gap, available, overflowCost, priority } = request;
+  const cost = (list: readonly Item[]): number =>
+    list.reduce((sum, item) => sum + widthOf(item) + gap, 0);
+
+  if (cost(items) <= available) {
+    return { inline: [...items], overflow: [], used: cost(items) };
+  }
+
+  // There IS an overflow, so its trigger now costs room too.
+  let room = available - overflowCost;
+  const keep = new Set<string>();
+  for (const item of priority ?? items) {
+    const next = widthOf(item) + gap;
+    if (next > room) continue;
+    room -= next;
+    keep.add(keyOf(item));
+  }
+  const inline = items.filter((item) => keep.has(keyOf(item)));
+  return {
+    inline,
+    overflow: items.filter((item) => !keep.has(keyOf(item))),
+    used: cost(inline) + overflowCost,
+  };
+}

package/src/components/utility/WorkflowStep/WorkflowStep.types.ts

@@ -1,3 +1,4 @@
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { ComponentProps } from 'react';
 
 /**
@@ -18,12 +19,12 @@ export type WorkflowStepOrientation = 'horizontal' | 'vertical';
 /**
  * Color theme for the workflow step component
  */
-export type WorkflowStepColor = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'neutral';
+export type WorkflowStepColor = Exclude<ColorValue, 'info'>;
 
 /**
  * Size variant for step indicators
  */
-export type WorkflowStepSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type WorkflowStepSize = SizeValue;
 
 /**
  * Individual step item configuration

package/src/components/utility/index.ts

@@ -2,6 +2,7 @@ export * from './AnimatedIcon';
 export * from './AspectRatio';
 export * from './InfiniteScroll';
 export * from './InstallPrompt';
+export * from './Overflow';
 export * from './Portal';
 export * from './Transition';
 export * from './VirtualList';

package/src/tokens/scales.ts

@@ -0,0 +1,153 @@
+import type { Theme } from '@mui/material/styles';
+
+/**
+ * THE TWO VOCABULARIES EVERY COMPONENT SPEAKS.
+ *
+ * Before this file the package had both halves of every argument at once: 26
+ * components sized themselves `xs|sm|md|lg|xl` and four used MUI's
+ * `small|medium|large`; 14 coloured themselves `danger|neutral` and 15 used
+ * MUI's `error`. Nothing enforced either, because most of these props were
+ * spelled out as inline unions and a couple were plain `string`.
+ *
+ * That is not a tidiness problem. A caller learns the vocabulary from whichever
+ * component they used first, and the wrong half is not rejected — it reaches MUI
+ * as an unknown value and silently falls back. `Chip` shipped with `color?:
+ * string` and MUI's `small|medium`, so `color="danger"` rendered grey and
+ * `size="sm"` rendered medium; twelve live call sites were doing exactly that,
+ * and every test passed because they all asserted on text.
+ *
+ * So the vocabulary is declared once, here, and components derive from it.
+ *
+ * DERIVE, DON'T COPY, AND SUBSET HONESTLY. A component that cannot draw the
+ * whole scale narrows with `Extract` rather than restating a union — an
+ * independent copy is what drifts. And it narrows rather than accepting the lot:
+ * a MUI chip draws two sizes, so putting `lg` in its type would promise
+ * something nothing can render.
+ *
+ *     size?: Extract<SizeValue, 'sm' | 'md'>;
+ *
+ * A component whose size or colour is not this concept at all keeps its own type
+ * — `Scrollbar`'s `thin|medium|thick` is a track width, `Sheet`'s `full` is a
+ * viewport fraction, `LazyImage`'s size is pixels. Forcing those into the scale
+ * would be consistency for its own sake.
+ */
+
+/**
+ * The house size scale.
+ *
+ * Abbreviated, because that is what 26 of the 30 components with a real size
+ * already used and what every caller has been taught to write.
+ */
+export type SizeValue = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * The house colour vocabulary.
+ *
+ * `danger` and `neutral` are OURS; the rest are MUI's own names already. That
+ * sentence started life in `Button.tsx`, which is the component most callers
+ * meet first and therefore the one that taught the vocabulary — so it is the one
+ * the rest of the package follows.
+ *
+ * Components that hand these to MUI translate at the boundary (`danger` →
+ * `error`, `neutral` → `default` or `inherit` depending on what the underlying
+ * component calls its unaccented state). The translation must be a real mapping
+ * and never a cast: a cast is precisely what let `danger` through untouched and
+ * had MUI fall back to grey.
+ */
+export type ColorValue =
+  | 'primary'
+  | 'secondary'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 'danger'
+  | 'neutral';
+
+/* ── The MUI boundary ─────────────────────────────────────────────────────── */
+
+/** What MUI calls a size. Three entries against our five. */
+export type MuiSize = 'small' | 'medium' | 'large';
+
+/**
+ * The house scale collapsed onto MUI's three.
+ *
+ * Five onto three loses information, and it loses it at the ends on purpose:
+ * `xs`/`sm` both draw small and `lg`/`xl` both draw large, because MUI has no
+ * fourth and fifth step to give them. A component that genuinely needs five
+ * distinct sizes styles them itself rather than routing through here — this is
+ * for the ones that just forward the prop.
+ */
+export const muiSize = (size: SizeValue): MuiSize => {
+  if (size === 'xs' || size === 'sm') return 'small';
+  return size === 'md' ? 'medium' : 'large';
+};
+
+/** What MUI calls a semantic colour on most components. */
+export type MuiColor = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'error';
+
+/**
+ * The house vocabulary translated for MUI, with the caller naming its neutral.
+ *
+ * `neutral` is the awkward one: MUI spells the unaccented state `default` on a
+ * chip, `inherit` on a button and an icon button, and `grey` in the palette. So
+ * the caller passes the word its own MUI component uses rather than this
+ * pretending there is one answer.
+ *
+ * A MAPPING, NEVER A CAST. The cast is what let `danger` reach MUI untouched and
+ * silently fall back to grey.
+ */
+export function muiColor<N extends string>(color: ColorValue, neutralAs: N): MuiColor | N {
+  if (color === 'danger') return 'error';
+  return color === 'neutral' ? neutralAs : color;
+}
+
+/**
+ * The house vocabulary as a `theme.palette` key.
+ *
+ * Separate from {@link muiColor} because the palette has no `default` and no
+ * `inherit` — an unaccented colour there is `grey`.
+ */
+export type PaletteKey = MuiColor | 'grey';
+
+export const paletteKey = (color: ColorValue): PaletteKey =>
+  color === 'danger' ? 'error' : color === 'neutral' ? 'grey' : color;
+
+/**
+ * A `ColorValue` resolved to a four-stop accent from the theme.
+ *
+ * `paletteKey` is not enough on its own for anything that reads `.main`: MUI's
+ * palette has no neutral `PaletteColor`, and `palette.grey` is a 50–900 ramp
+ * with no `main`, `light`, `dark` or `contrastText` on it at all. So `neutral`
+ * is resolved from the ramp here, once, instead of every component discovering
+ * the same hole and branching around it.
+ *
+ * Typed against the theme structurally so this file does not drag in MUI's
+ * `Theme` and become a dependency of everything that imports a token.
+ */
+export interface Accent {
+  main: string;
+  light: string;
+  dark: string;
+  contrastText: string;
+}
+
+export function accentFor(theme: Theme, color: ColorValue): Accent {
+  if (color === 'neutral') {
+    const grey = theme.palette.grey;
+    return {
+      // Explicit fallbacks: the ramp is indexed, and under
+      // `noUncheckedIndexedAccess` every stop is `string | undefined`.
+      main: grey[600] ?? '#757575',
+      light: grey[400] ?? '#bdbdbd',
+      dark: grey[800] ?? '#424242',
+      // Grey 600 carries white text in both themes.
+      contrastText: '#fff',
+    };
+  }
+  // Past the `neutral` return, `paletteKey` can only produce a `MuiColor` — but
+  // its signature still admits `'grey'`, and TS cannot narrow a return type by
+  // the argument. Naming the key here keeps the accent branch honestly typed
+  // instead of casting the hole shut.
+  const key: MuiColor = color === 'danger' ? 'error' : color;
+  return theme.palette[key];
+}