@ultimat3/ui 1.0.0 → 1.2.0

package/src/components/Drawer.module.scss

@@ -10,9 +10,7 @@
   color: t.role('fg');
   box-shadow: t.shadow(xl);
 
-  &::backdrop {
-    background: t.role('scrim', 0.45);
-  }
+  @include t.scrim-backdrop;
 }
 
 .side-inline-start {

package/src/components/IconButton.module.scss

@@ -10,10 +10,7 @@
   color: t.role('fg-muted');
   cursor: pointer;
 
-  &:disabled {
-    opacity: 0.55;
-    cursor: not-allowed;
-  }
+  @include t.disabled;
 }
 
 .round {
@@ -44,39 +41,12 @@
   font-size: t.text(lg);
 }
 
-.tone-neutral {
-  --tone: #{t.role('fg-strong')};
-  --tone-soft: #{t.role('bg-soft')};
-}
-
-.tone-accent {
-  --tone: #{t.role('accent')};
-  --tone-soft: #{t.role('accent', 0.12)};
-}
-
-.tone-success {
-  --tone: #{t.role('success')};
-  --tone-soft: #{t.role('success-soft')};
-}
-
-.tone-warning {
-  --tone: #{t.role('warning')};
-  --tone-soft: #{t.role('warning-soft')};
-}
-
-.tone-danger {
-  --tone: #{t.role('danger')};
-  --tone-soft: #{t.role('danger-soft')};
-}
-
-.tone-info {
-  --tone: #{t.role('info')};
-  --tone-soft: #{t.role('info-soft')};
-}
+@include t.tone-classes;
 
 .variant-primary {
   background: var(--tone);
-  color: t.role('accent-fg');
+  // `--tone-fg` rather than a hardcoded accent-fg: a danger IconButton needs danger's on-colour.
+  color: var(--tone-fg);
 }
 
 .variant-secondary {

package/src/components/PageHeader.module.scss

@@ -0,0 +1,47 @@
+@use '../tokens' as t;
+
+.pageHeader {
+  @include t.column(t.space(3));
+  padding-block-end: t.space(5);
+  border-block-end: 1px solid t.role('line');
+}
+
+// Wraps rather than shrinking: a long title must never squeeze the actions off the row.
+.bar {
+  @include t.row(t.space(4), flex-start, space-between);
+  flex-wrap: wrap;
+}
+
+.titles {
+  @include t.row(t.space(3), flex-start);
+  min-inline-size: 0;
+  flex: 1 1 20rem;
+}
+
+.media {
+  display: inline-flex;
+  flex: none;
+}
+
+.text {
+  @include t.column(t.space(1));
+  min-inline-size: 0;
+}
+
+.title {
+  color: t.role('fg-strong');
+  font-size: t.text(2xl);
+  line-height: t.leading(tight);
+}
+
+.description {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  max-inline-size: 68ch;
+}
+
+.actions {
+  @include t.row(t.space(2), center, flex-end);
+  flex-wrap: wrap;
+  flex: none;
+}

package/src/components/PageHeader.tsx

@@ -0,0 +1,46 @@
+// The top of a screen: breadcrumbs, the page's one heading, a description, and the actions that
+// belong to the page rather than to a row in it. Hand-rolled, this is where the heading level,
+// the landmark and the action alignment go wrong; here it is one component with one shape.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import { Breadcrumb, type BreadcrumbItem } from './Breadcrumb';
+import { type HeadingLevel, headingTag } from './heading-level';
+import styles from './PageHeader.module.scss';
+
+export interface PageHeaderProps {
+  /** Already-translated page title. Rendered as the heading, once. */
+  title: string;
+  /** Already-translated supporting line under the title. */
+  description?: string | undefined;
+  /** Trailing controls — a Button, a Toolbar. Wraps under the title on narrow viewports. */
+  actions?: JSX.Element | undefined;
+  breadcrumbs?: readonly BreadcrumbItem[] | undefined;
+  /** Heading level. 1 by default: a screen has exactly one h1, and this is it. */
+  level?: HeadingLevel | undefined;
+  /** Rendered before the title — an avatar, an icon, a status dot. */
+  media?: JSX.Element | undefined;
+  class?: string | undefined;
+}
+
+export function PageHeader(props: PageHeaderProps): JSX.Element {
+  const Heading = headingTag(props.level ?? 1);
+
+  return (
+    <header class={cx(styles['pageHeader'], props.class)}>
+      {props.breadcrumbs === undefined ? null : <Breadcrumb items={props.breadcrumbs} />}
+      <div class={styles['bar']}>
+        <div class={styles['titles']}>
+          {props.media === undefined ? null : <div class={styles['media']}>{props.media}</div>}
+          <div class={styles['text']}>
+            <Heading class={styles['title']}>{props.title}</Heading>
+            {props.description === undefined ? null : (
+              <p class={styles['description']}>{props.description}</p>
+            )}
+          </div>
+        </div>
+        {props.actions === undefined ? null : <div class={styles['actions']}>{props.actions}</div>}
+      </div>
+    </header>
+  );
+}

package/src/components/Section.module.scss

@@ -0,0 +1,38 @@
+@use '../tokens' as t;
+
+.section {
+  @include t.column(t.space(4));
+  min-inline-size: 0;
+}
+
+.head {
+  @include t.row(t.space(4), flex-end, space-between);
+  flex-wrap: wrap;
+}
+
+.text {
+  @include t.column(t.space(1));
+  min-inline-size: 0;
+}
+
+.title {
+  color: t.role('fg-strong');
+  font-size: t.text(lg);
+  line-height: t.leading(snug);
+}
+
+.description {
+  color: t.role('fg-muted');
+  font-size: t.text(sm);
+  max-inline-size: 68ch;
+}
+
+.actions {
+  @include t.row(t.space(2), center, flex-end);
+  flex-wrap: wrap;
+  flex: none;
+}
+
+.body {
+  min-inline-size: 0;
+}

package/src/components/Section.tsx

@@ -0,0 +1,55 @@
+// A titled block inside a page. Exists so a screen's second-level structure is a labelled
+// landmark with a real heading — `aria-labelledby` wired to the heading it renders — instead of
+// a <div> with bold text, which is what an unassisted layout always becomes.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { type HeadingLevel, headingTag } from './heading-level';
+import styles from './Section.module.scss';
+
+export interface SectionProps {
+  children: JSX.Element;
+  /** Already-translated section title. Omit for an unlabelled grouping. */
+  title?: string | undefined;
+  /** Already-translated supporting line under the title. */
+  description?: string | undefined;
+  /** Controls that act on this section only. */
+  actions?: JSX.Element | undefined;
+  /** Heading level. 2 by default — the level under a PageHeader's h1. */
+  level?: HeadingLevel | undefined;
+  as?: 'section' | 'article' | 'aside' | undefined;
+  class?: string | undefined;
+}
+
+export function Section(props: SectionProps): JSX.Element {
+  const Tag = props.as ?? 'section';
+  const Heading = headingTag(props.level ?? 2);
+  const titleId = useId('section');
+
+  return (
+    <Tag
+      class={cx(styles['section'], props.class)}
+      aria-labelledby={props.title === undefined ? undefined : titleId}
+    >
+      {props.title === undefined && props.actions === undefined ? null : (
+        <div class={styles['head']}>
+          <div class={styles['text']}>
+            {props.title === undefined ? null : (
+              <Heading id={titleId} class={styles['title']}>
+                {props.title}
+              </Heading>
+            )}
+            {props.description === undefined ? null : (
+              <p class={styles['description']}>{props.description}</p>
+            )}
+          </div>
+          {props.actions === undefined ? null : (
+            <div class={styles['actions']}>{props.actions}</div>
+          )}
+        </div>
+      )}
+      <div class={styles['body']}>{props.children}</div>
+    </Tag>
+  );
+}

package/src/components/Tabs.module.scss

@@ -49,10 +49,7 @@
     background: t.role('bg-soft');
   }
 
-  &:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-  }
+  @include t.disabled(0.5);
 
   &[aria-selected='true'] {
     color: t.role('accent');

package/src/components/Toolbar.module.scss

@@ -0,0 +1,26 @@
+@use '../tokens' as t;
+
+.toolbar {
+  @include t.row(t.space(3), center, space-between);
+  flex-wrap: wrap;
+  min-inline-size: 0;
+}
+
+.surface {
+  @include t.surface('surface', 'xs');
+  padding-block: t.space(3);
+  padding-inline: t.space(4);
+}
+
+.start {
+  @include t.row(t.space(2), center);
+  flex: 1 1 auto;
+  flex-wrap: wrap;
+  min-inline-size: 0;
+}
+
+.end {
+  @include t.row(t.space(2), center, flex-end);
+  flex: none;
+  flex-wrap: wrap;
+}

package/src/components/Toolbar.tsx

@@ -0,0 +1,48 @@
+// The control strip above a table or a list: filters and search at the inline start, actions at
+// the inline end. `role="toolbar"` with the same roving-tabindex helper Tabs uses, so arrow keys
+// move between controls and the strip costs one Tab stop instead of a dozen.
+
+import type { JSX } from 'solid-js';
+import { createRovingTabindex, focusableWithin } from '../a11y';
+import { cx } from '../cx';
+import { useUi } from '../theme/context';
+import styles from './Toolbar.module.scss';
+
+export interface ToolbarProps {
+  /** Leading controls — search, filters, a Select. */
+  children: JSX.Element;
+  /** Trailing controls, pushed to the inline end. */
+  actions?: JSX.Element | undefined;
+  /** Already-translated accessible name. Required: an unnamed toolbar is an unnamed group. */
+  label: string;
+  /** Renders the strip on a raised, bordered surface. */
+  surface?: boolean | undefined;
+  class?: string | undefined;
+}
+
+export function Toolbar(props: ToolbarProps): JSX.Element {
+  const ui = useUi();
+  let strip: HTMLDivElement | undefined;
+
+  // Arrows follow the writing direction; `focusableWithin` skips anything hidden or disabled.
+  const onKeyDown = createRovingTabindex(
+    () => (strip === undefined ? [] : focusableWithin(strip)),
+    { orientation: 'horizontal', dir: ui.dir, loop: false },
+  );
+
+  return (
+    <div
+      ref={(el: HTMLDivElement) => {
+        strip = el;
+      }}
+      class={cx(styles['toolbar'], props.surface === true && styles['surface'], props.class)}
+      role="toolbar"
+      aria-label={props.label}
+      aria-orientation="horizontal"
+      onKeyDown={onKeyDown}
+    >
+      <div class={styles['start']}>{props.children}</div>
+      {props.actions === undefined ? null : <div class={styles['end']}>{props.actions}</div>}
+    </div>
+  );
+}

package/src/components/app-shell-view.ts

@@ -0,0 +1,35 @@
+// AppShell's two rules, kept away from the markup: the id the skip link points at is derived
+// from the same place the <main> gets it, and which landmarks the frame emits in which order.
+// Both are silent failures when wrong — a skip link to nowhere, or two <main> elements.
+
+export type ShellLandmark = 'banner' | 'navigation' | 'main' | 'contentinfo';
+
+export interface ShellIds {
+  readonly mainId: string;
+  /** Always `#` + `mainId`. One derivation, so the link and the target cannot drift. */
+  readonly skipHref: string;
+}
+
+export interface ShellSlots {
+  readonly header: boolean;
+  readonly sidebar: boolean;
+  readonly footer: boolean;
+}
+
+export function shellIds(base: string): ShellIds {
+  const mainId = `${base}-main`;
+  return { mainId, skipHref: `#${mainId}` };
+}
+
+/**
+ * DOM order, which is also screen-reader order: banner, then navigation, then main, then
+ * contentinfo. `main` is unconditional — a shell with no main region is not a page.
+ */
+export function shellLandmarks(slots: ShellSlots): readonly ShellLandmark[] {
+  const out: ShellLandmark[] = [];
+  if (slots.header) out.push('banner');
+  if (slots.sidebar) out.push('navigation');
+  out.push('main');
+  if (slots.footer) out.push('contentinfo');
+  return out;
+}

package/src/components/heading-level.ts

@@ -0,0 +1,25 @@
+// Which heading element a composite renders. A rule, not markup: PageHeader and Section both
+// need it, and a page whose headings skip a level is a screen-reader outline with holes — so the
+// level is a prop with one mapping, never a hardcoded <h2> inside a component.
+
+import { invalidValueError } from '../errors';
+
+export const HEADING_LEVELS = [1, 2, 3, 4, 5, 6] as const;
+export type HeadingLevel = (typeof HEADING_LEVELS)[number];
+export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+/** `2` → `'h2'`. Throws `X_UI_INVALID_VALUE` for anything off the scale. */
+export function headingTag(level: HeadingLevel): HeadingTag {
+  if (!(HEADING_LEVELS as readonly number[]).includes(level)) {
+    throw invalidValueError('heading', level, 'a heading level from 1 to 6');
+  }
+  return `h${level}` as HeadingTag;
+}
+
+/**
+ * The level for content nested under a heading. Clamped at 6 rather than throwing: a deeply
+ * nested Section is a layout the app is allowed to build, and HTML has no `<h7>`.
+ */
+export function nextHeadingLevel(level: HeadingLevel): HeadingLevel {
+  return (level < 6 ? level + 1 : 6) as HeadingLevel;
+}

package/src/errors.ts

@@ -35,12 +35,39 @@ export class UiError extends UltimateError {
   }
 }
 
-/** A component asked for a token role that the SCSS source does not define. */
-export function unknownTokenError(kind: string, name: string, known: readonly string[]): UiError {
+/**
+ * A component asked for a token role that the SCSS source does not define. `source` is the
+ * partial that declares the scale — defaulted, because most kinds pluralise (`colors`), and
+ * named explicitly by the ones that do not (`radius`), so the `fix:` is always a real path.
+ */
+export function unknownTokenError(
+  kind: string,
+  name: string,
+  known: readonly string[],
+  source = `_${kind}s.scss`,
+): UiError {
   return new UiError({
     code: UI_ERROR_CODES.tokenUnknown,
     cause: `unknown ${kind} token "${name}"; known roles: ${known.join(', ')}`,
-    fix: `use one of the ${kind} roles above, or add "${name}" to packages/ui/src/tokens/_${kind}s.scss and mirror it in tokens.ts`,
+    fix: `use one of the ${kind} roles above, or add "${name}" to packages/ui/src/tokens/${source} and mirror it in tokens.ts`,
+  });
+}
+
+/**
+ * A `defineTheme()` override held something that is not a token value. Strict on purpose: the
+ * result is interpolated into a `<style>` element, so a value carrying `;`, `}` or `</style>` is
+ * a CSS injection, not a typo.
+ */
+export function invalidBrandTokenError(
+  scope: string,
+  name: string,
+  value: unknown,
+  expected: string,
+): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `defineTheme() override ${scope}.${name} is ${JSON.stringify(value)}, which is not ${expected}`,
+    fix: `pass ${expected} to defineTheme(), e.g. defineTheme({ colors: { light: { accent: '31 110 178' } } })`,
   });
 }
 

package/src/i18n-keys.ts

@@ -17,6 +17,10 @@ export const UI_KEYS = {
   sortAscending: 'ui.sort.ascending',
   sortDescending: 'ui.sort.descending',
   breadcrumb: 'ui.breadcrumb',
+  /** AppShell's skip link — the first Tab stop on every page. */
+  skip: 'ui.skip',
+  /** AppShell's sidebar landmark name. */
+  navigation: 'ui.navigation',
   menu: 'ui.menu',
   more: 'ui.more',
   required: 'ui.required',

package/src/index.ts

@@ -21,8 +21,12 @@ export {
 export type { AlertProps } from './components/Alert';
 // --- components --------------------------------------------------------------
 export { Alert } from './components/Alert';
+export type { AppShellProps } from './components/AppShell';
+export { AppShell } from './components/AppShell';
 export type { AvatarProps } from './components/Avatar';
 export { Avatar, initialsOf } from './components/Avatar';
+export type { ShellIds, ShellLandmark, ShellSlots } from './components/app-shell-view';
+export { shellIds, shellLandmarks } from './components/app-shell-view';
 export type { BadgeProps } from './components/Badge';
 export { Badge } from './components/Badge';
 export type { BreadcrumbItem, BreadcrumbProps } from './components/Breadcrumb';
@@ -63,6 +67,8 @@ export type { FormProps } from './components/Form';
 export { Form } from './components/Form';
 export type { GridProps } from './components/Grid';
 export { Grid } from './components/Grid';
+export type { HeadingLevel, HeadingTag } from './components/heading-level';
+export { HEADING_LEVELS, headingTag, nextHeadingLevel } from './components/heading-level';
 export type { IconButtonProps } from './components/IconButton';
 export { IconButton } from './components/IconButton';
 export type { ImageProps } from './components/Image';
@@ -82,6 +88,8 @@ export { Money } from './components/Money';
 export type { MoneyFormatter, MoneyInput, MoneyViewOptions } from './components/money-view';
 // --- formatting cores (pure, renderer-free) ----------------------------------
 export { moneyText, toMoney } from './components/money-view';
+export type { PageHeaderProps } from './components/PageHeader';
+export { PageHeader } from './components/PageHeader';
 export type { PaginationProps } from './components/Pagination';
 export { Pagination } from './components/Pagination';
 export type { Placement, PopoverProps } from './components/Popover';
@@ -92,6 +100,8 @@ export type { RelativeTimeProps } from './components/RelativeTime';
 export { RelativeTime } from './components/RelativeTime';
 export type { RelativeTimeOptions } from './components/relative-time-view';
 export { relativeTimeText } from './components/relative-time-view';
+export type { SectionProps } from './components/Section';
+export { Section } from './components/Section';
 export type { SelectOption, SelectProps } from './components/Select';
 export { Select } from './components/Select';
 export type { SkeletonProps } from './components/Skeleton';
@@ -116,6 +126,8 @@ export type { ThemeChoice, ThemeToggleProps } from './components/ThemeToggle';
 export { ThemeToggle } from './components/ThemeToggle';
 export type { ToastProps, ToastRegionProps } from './components/Toast';
 export { Toast, ToastRegion } from './components/Toast';
+export type { ToolbarProps } from './components/Toolbar';
+export { Toolbar } from './components/Toolbar';
 export type { TooltipProps } from './components/Tooltip';
 export { Tooltip } from './components/Tooltip';
 export type { Align, ButtonVariant, Size, SpaceStep, Tone } from './components/variants';
@@ -126,6 +138,7 @@ export type { ClassValue } from './cx';
 export { cx } from './cx';
 export type { UiErrorCode } from './errors';
 export {
+  invalidBrandTokenError,
   invalidThemeError,
   invalidValueError,
   runtimeMissingError,
@@ -135,6 +148,8 @@ export {
 } from './errors';
 export type { UiKey } from './i18n-keys';
 export { UI_KEYS } from './i18n-keys';
+export type { Brand, BrandInput, FontSlot } from './theme/brand';
+export { brandStyleTag, defineTheme, FONT_SLOTS } from './theme/brand';
 export type { Direction, UiContextValue } from './theme/context';
 export {
   defaultUiContext,
@@ -177,7 +192,18 @@ export {
   toggleTheme,
   watchOsTheme,
 } from './theme/theme';
-export type { ColorRole, Theme } from './tokens/tokens';
+export type { Channels } from './tokens/contrast';
+export {
+  AA_LARGE,
+  AA_TEXT,
+  CHANNELS_PATTERN,
+  contrastRatio,
+  meetsContrast,
+  parseChannels,
+  relativeLuminance,
+  roleContrast,
+} from './tokens/contrast';
+export type { ColorRole, RadiusName, Theme } from './tokens/tokens';
 // --- tokens ------------------------------------------------------------------
 export {
   assertColorRole,