@gtivr4/a1-design-system-react 0.4.1 → 0.5.0

package/src/components/data-table/DataTable.d.ts

@@ -0,0 +1,83 @@
+import * as React from "react";
+
+export interface DataTableColumn {
+  key: string;
+  label: string;
+  type?: "text" | "number" | "currency" | "date" | "badge" | "avatar" | "link" | "actions";
+  align?: "start" | "center" | "end";
+  width?: string;
+  sortable?: boolean;
+  sortAccessor?: (row: Record<string, unknown>) => unknown;
+  searchAccessor?: (row: Record<string, unknown>) => unknown;
+  statusMap?: Record<string, "neutral" | "info" | "success" | "warn" | "error">;
+  currencySymbol?: string;
+}
+
+export interface DataTableSortState {
+  key: string;
+  direction: "asc" | "desc";
+}
+
+export interface DataTableFilter {
+  key: string;
+  label: string;
+  type?: "single" | "multi";
+  options: Array<{ value: string; label: string }>;
+}
+
+export interface DataTableProps extends React.HTMLAttributes<HTMLDivElement> {
+  columns?: DataTableColumn[];
+  rows?: Record<string, unknown>[];
+  /**
+   * Cell spacing density.
+   * Omit (default) to auto-select density based on the available container width.
+   */
+  size?: "comfortable" | "default" | "compact";
+  /** Alternate row shading. Default: false */
+  zebra?: boolean;
+  /** Enable horizontal scroll on the table. Default: false */
+  scrollable?: boolean;
+  /** Accessible caption for the table */
+  caption?: string;
+  /** Controlled current page (1-based) */
+  page?: number;
+  /** Uncontrolled initial page. Default: 1 */
+  defaultPage?: number;
+  /** Number of rows per page for built-in pagination */
+  pageSize?: number;
+  /** Total page count for server-side pagination */
+  totalPages?: number;
+  /** Total row count for server-side row counter */
+  totalRows?: number;
+  /** Called when the active page changes */
+  onPageChange?: (page: number) => void;
+  /** Controlled sort state */
+  sort?: DataTableSortState | null;
+  /** Uncontrolled initial sort state */
+  defaultSort?: DataTableSortState;
+  /** Called when sort changes */
+  onSortChange?: (sort: DataTableSortState | null) => void;
+  filters?: DataTableFilter[];
+  filterValue?: Record<string, unknown>;
+  defaultFilterValue?: Record<string, unknown>;
+  onFilterChange?: (value: Record<string, unknown>) => void;
+  searchValue?: string;
+  defaultSearchValue?: string;
+  onSearchChange?: (value: string) => void;
+  searchColumn?: string;
+  defaultSearchColumn?: string;
+  onSearchColumnChange?: (column: string) => void;
+  searchableColumns?: Array<{ key: string; label: string }>;
+  /** Enable row selection. Default: false */
+  selectable?: boolean;
+  selectedRowIds?: (string | number)[];
+  defaultSelectedRowIds?: (string | number)[];
+  onSelectedRowIdsChange?: (ids: string[]) => void;
+  onDeleteSelected?: (rows: Record<string, unknown>[], ids: string[]) => void;
+  getRowId?: (row: Record<string, unknown>, index: number) => string | number;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  emptyIcon?: string;
+}
+
+export declare function DataTable(props: DataTableProps): React.ReactElement;

package/src/components/dialog/Dialog.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+
+export interface DialogProps extends React.DialogHTMLAttributes<HTMLDialogElement> {
+  /** Whether the dialog is visible. Default: false */
+  open?: boolean;
+  /** Called when the user closes the dialog (Escape, close button, or backdrop click) */
+  onClose?: () => void;
+  /** Dialog title shown in the header */
+  title?: string;
+  /** Footer content — wrapped in a right-aligned `ButtonContainer` */
+  footer?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+export declare function Dialog(props: DialogProps): React.ReactElement;

package/src/components/dialog/dialog.css

@@ -12,8 +12,12 @@
 }
 
 .a1-dialog[open] {
-  display: flex;
-  flex-direction: column;
+  /* CSS Grid instead of Flex: Safari collapses flex: 1 children when the
+     container has only max-height but no explicit height. Grid resolves
+     track sizes against the constrained container first, so 1fr works. */
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
+  grid-auto-rows: auto;
   gap: var(--base-spacing-16);
 }
 
@@ -45,8 +49,8 @@
 }
 
 .a1-dialog__body {
-  flex: 1;
   overflow-y: auto;
+  min-height: 0;
 }
 
 .a1-dialog__footer {

package/src/components/divider/Divider.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+
+type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+type Orientation = "horizontal" | "vertical";
+
+export interface DividerProps extends React.HTMLAttributes<HTMLHRElement> {
+  /**
+   * Line orientation. Responsive object syntax supported. Default: "horizontal"
+   * @example orientation={{ xs: "horizontal", md: "vertical" }}
+   */
+  orientation?: Orientation | Partial<Record<Breakpoints, Orientation>>;
+  /** Visual style. Default: "subtle" */
+  variant?: "subtle" | "strong" | "accent" | "dashed" | "dotted";
+  /** Line thickness. Default: "xs" */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Block-axis margin (space above and below for horizontal, left/right for vertical). Default: "sm" */
+  space?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
+  /** Whether this divider is purely decorative (no semantic role). Default: true */
+  decorative?: boolean;
+}
+
+export declare function Divider(props: DividerProps): React.ReactElement;

package/src/components/field/SelectField.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+
+export interface SelectFieldProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  hint?: string;
+  /** Error message — replaces hint and marks the field invalid */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  /** Label position. Inherits from parent `Fieldset` when omitted. Default: "above" */
+  labelPosition?: "above" | "before";
+  required?: boolean;
+  disabled?: boolean;
+  /** Element rendered inside the field control */
+  inputOverlay?: React.ReactNode;
+  /** `<option>` elements */
+  children?: React.ReactNode;
+}
+
+export declare const SelectField: React.ForwardRefExoticComponent<SelectFieldProps & React.RefAttributes<HTMLSelectElement>>;

package/src/components/field/TextField.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+export interface TextFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "placeholder"> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  hint?: string;
+  /** Error message — replaces hint and marks the field invalid */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  /** Label position. Inherits from parent `Fieldset` when omitted. Default: "above" */
+  labelPosition?: "above" | "before";
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** Element rendered inside the field control (e.g. a unit suffix) */
+  inputOverlay?: React.ReactNode;
+}
+
+export declare const TextField: React.ForwardRefExoticComponent<TextFieldProps & React.RefAttributes<HTMLInputElement>>;

package/src/components/field/TextareaField.d.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+
+export interface TextareaFieldProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size" | "rows"> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  hint?: string;
+  /** Error message — replaces hint and marks the field invalid */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  /** Label position. Inherits from parent `Fieldset` when omitted. Default: "above" */
+  labelPosition?: "above" | "before";
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /**
+   * Initial visible row height. Pass a number for exact rows or a size token.
+   * sm=2 · md=4 · lg=8 · xl=12. Default: "md"
+   */
+  rows?: "sm" | "md" | "lg" | "xl" | number;
+  /** Maximum character count */
+  maxLength?: number;
+  /** Show a character counter. Auto-enabled when `maxLength` is set. Default: false */
+  showCount?: boolean;
+}
+
+export declare const TextareaField: React.ForwardRefExoticComponent<TextareaFieldProps & React.RefAttributes<HTMLTextAreaElement>>;

package/src/components/field-row/FieldRow.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+
+export interface FieldRowProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Lays out multiple field components side by side in a single row. */
+  children?: React.ReactNode;
+}
+
+export declare function FieldRow(props: FieldRowProps): React.ReactElement;

package/src/components/fieldset/Fieldset.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+
+export interface FieldsetProps extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /** `<legend>` text for the field group */
+  legend?: string;
+  /**
+   * Size density applied to all child fields via context.
+   * Individual fields can override this.
+   */
+  size?: "comfortable" | "default" | "compact";
+  /**
+   * Label position applied to all child fields via context.
+   * Individual fields can override this.
+   */
+  labelPosition?: "above" | "before";
+  /**
+   * Show a "* Required field" note below the legend.
+   * Only shown for "default" and "compact" sizes (comfortable fields show inline badges).
+   * Default: false
+   */
+  markRequired?: boolean;
+  /** Add a subtle surface background to the fieldset. Default: false */
+  surface?: boolean;
+  children?: React.ReactNode;
+}
+
+export declare function Fieldset(props: FieldsetProps): React.ReactElement;

package/src/components/figure/Figure.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+
+type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+
+export interface FigureProps extends React.HTMLAttributes<HTMLElement> {
+  /** Image source URL */
+  src: string;
+  /** Image alt text. Pass "" for decorative images. */
+  alt?: string;
+  /** Caption text or React node rendered as `<figcaption>` */
+  caption?: React.ReactNode;
+  /** Render caption visually hidden (screen-reader only). Default: false */
+  captionSrOnly?: boolean;
+  /** Caption alignment. Default: "start" */
+  captionPosition?: "start" | "center";
+  /** Border radius on the image. */
+  radius?: "none" | "sm" | "md" | "lg";
+  /** Constrain figure width. */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Horizontal alignment of the figure. Default: "start" */
+  align?: "start" | "center" | "end";
+  /** Top margin. */
+  marginTop?: "sm" | "md" | "lg";
+  /** Bottom margin. */
+  marginBottom?: "sm" | "md" | "lg";
+  /**
+   * Pull the figure outside its container padding using `Bleed`.
+   * Pass `true` for symmetric bleed or a numeric spacing token for inline-only.
+   */
+  bleed?: boolean | SpacingToken;
+  /** Extra class names on the `<figure>` element */
+  className?: string;
+  /** Extra class names on the `<img>` element */
+  imgClassName?: string;
+  /** Inline styles for the `<img>` element */
+  imgStyle?: React.CSSProperties;
+}
+
+export declare function Figure(props: FigureProps): React.ReactElement;

package/src/components/grid/Grid.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+
+type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+type GapKey = "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+type ColSpan = number | "full";
+
+export interface GridProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Number of columns. Pass a number for a fixed count, or a responsive object.
+   * @example columns={{ xs: 1, md: 2, lg: 3 }}
+   */
+  columns?: number | Partial<Record<Breakpoints, number>>;
+  /** Gap applied to both row and column. Semantic token ("sm"–"xxl") or numeric spacing value. */
+  gap?: GapKey;
+  /** Row gap override. Falls back to `gap`. */
+  rowGap?: GapKey;
+  /** Column gap override. Falls back to `gap`. */
+  columnGap?: GapKey;
+  /** Grid layout preset. Default: "default" */
+  layout?: "default" | "bento";
+  /** CSS value for `grid-auto-rows` */
+  autoRows?: string;
+  children?: React.ReactNode;
+}
+
+export interface GridItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Column span. Pass a number, "full", or a responsive object.
+   * @example span={{ xs: "full", md: 2 }}
+   */
+  span?: ColSpan | Partial<Record<Breakpoints, ColSpan>>;
+  /** Row span. Pass a number or a responsive object. */
+  rowSpan?: number | Partial<Record<Breakpoints, number>>;
+  children?: React.ReactNode;
+}
+
+export declare function Grid(props: GridProps): React.ReactElement;
+export declare function GridItem(props: GridItemProps): React.ReactElement;

package/src/components/heading/Heading.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+
+type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+type HeadingSize = "xxl" | "xl" | "lg" | "md" | "sm" | "xs";
+type DisplaySize = "sm" | "md" | "lg" | "xl" | "xxl" | "jumbo" | "xJumbo";
+
+export interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  /** HTML heading level. Default: "h2" */
+  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+  /**
+   * Typography type — drives the available size scale.
+   * "heading" uses the text hierarchy scale; "display" uses the larger editorial scale.
+   * Default: "heading"
+   */
+  type?: "heading" | "display";
+  /**
+   * Size within the active type scale. Responsive object syntax supported.
+   * Heading sizes: xs | sm | md | lg | xl | xxl
+   * Display sizes: sm | md | lg | xl | xxl | jumbo | xJumbo
+   * @example size={{ xs: "lg", md: "xl" }}
+   */
+  size?: HeadingSize | DisplaySize | Partial<Record<Breakpoints, HeadingSize | DisplaySize>>;
+  /** Text colour. Default: "default" */
+  color?: "default" | "muted" | "accent";
+  /** Add bottom margin. Useful when followed by body text. */
+  margin?: "sm" | "md" | "lg";
+  /** Apply text-wrap. "balance" distributes line lengths evenly — best for short headings. */
+  textWrap?: "balance";
+  /** Horizontal text alignment. "start"/"end" are logical aliases for LTR/RTL-safe alignment. */
+  align?: "left" | "center" | "right" | "start" | "end";
+  children?: React.ReactNode;
+}
+
+export interface HeadingMarkProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Visual decoration style. Default: "highlight" */
+  variant?: "highlight" | "underline";
+  /** Underline style (only applies when variant="underline"). Default: "swoop" */
+  underlineStyle?: "swoop" | "wave" | "sketch";
+  children?: React.ReactNode;
+}
+
+export declare function Heading(props: HeadingProps): React.ReactElement;
+export declare function HeadingMark(props: HeadingMarkProps): React.ReactElement;

package/src/components/heading/Heading.jsx

@@ -4,7 +4,7 @@ const headingSizes = ["xxl", "xl", "lg", "md", "sm", "xs"];
 const displaySizes = ["sm", "md", "lg", "xl", "xxl", "jumbo", "xJumbo"];
 const colors = ["default", "muted", "accent"];
 const margins = ["sm", "md", "lg"];
-const levels = ["h1", "h2", "h3", "h4", "h5", "h6"];
+const elements = ["h1", "h2", "h3", "h4", "h5", "h6", "p", "span"];
 const breakpoints = ["xs", "sm", "md", "lg", "xl"];
 const textWraps = ["balance"];
 const aligns = ["left", "center", "right", "start", "end"];
@@ -50,7 +50,7 @@ export function Heading({
   style,
   ...props
 }) {
-  const resolvedAs = levels.includes(Component) ? Component : "h2";
+  const resolvedAs = elements.includes(Component) ? Component : "h2";
   const isDisplay = type === "display";
   const validSizes = isDisplay ? displaySizes : headingSizes;
   const defaultSize = isDisplay ? "md" : (levelDefaults[resolvedAs] ?? "md");

package/src/components/icon/Icon.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+
+export interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Material Symbols icon name (e.g. "check_circle", "home", "arrow_back") */
+  name: string;
+  /**
+   * Variable font weight axis (100–700).
+   * Default is set via CSS token `--a1-icon-weight`.
+   */
+  weight?: number;
+  /**
+   * Grade axis — adjusts visual weight without changing size (-25–200).
+   * Default is set via CSS token `--a1-icon-grade`.
+   */
+  grade?: number;
+  /**
+   * Optical size axis — adjusts detail level (20, 24, 40, 48).
+   * Default is set via CSS token `--a1-icon-opsz`.
+   */
+  opticalSize?: 20 | 24 | 40 | 48;
+  /** Fill the icon shape. Default: false */
+  fill?: boolean;
+}
+
+export declare function Icon(props: IconProps): React.ReactElement;

package/src/components/icon-button/IconButton.d.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+
+export interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Material Symbols icon name */
+  icon: string;
+  /** Accessible label (used as `aria-label` and visible tooltip) */
+  label: string;
+  /** Visual style. Default: "tertiary" */
+  variant?: "tertiary" | "secondary" | "destructive" | "success";
+  disabled?: boolean;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+}
+
+export declare function IconButton(props: IconButtonProps): React.ReactElement;

package/src/components/inset/Inset.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+
+type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+
+export interface InsetProps extends React.HTMLAttributes<HTMLElement> {
+  /** Underlying element. Default: "div" */
+  as?: React.ElementType;
+  /** Base padding applied to all axes when no axis-specific value is set. Default: 16 */
+  space?: SpacingToken;
+  /** Block-axis (top/bottom) padding override. Falls back to `space`. */
+  block?: SpacingToken;
+  /** Inline-axis (left/right) padding override. Falls back to `space`. */
+  inline?: SpacingToken;
+  children?: React.ReactNode;
+}
+
+export declare function Inset(props: InsetProps): React.ReactElement;

package/src/components/inverse/Inverse.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+
+export interface InverseProps extends React.HTMLAttributes<HTMLElement> {
+  /** Underlying element. Default: "div" */
+  as?: React.ElementType;
+  children?: React.ReactNode;
+}
+
+export declare function Inverse(props: InverseProps): React.ReactElement;

package/src/components/link/Link.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /** Font size. Inherits from context when omitted. */
+  size?: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Font weight override. */
+  weight?: "normal" | "medium" | "semibold" | "bold";
+  /** Material Symbols icon name to show alongside the link text. */
+  icon?: string;
+  /** Position of the icon relative to the text. Default: "start" */
+  iconPosition?: "start" | "end";
+  children?: React.ReactNode;
+}
+
+export declare function Link(props: LinkProps): React.ReactElement;

package/src/components/list/List.d.ts

@@ -0,0 +1,40 @@
+import * as React from "react";
+
+type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+type ListSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+export interface ListProps extends React.HTMLAttributes<HTMLUListElement | HTMLOListElement> {
+  /** Underlying element — "ol" switches to ordered variant automatically. Default: "ul" */
+  as?: "ul" | "ol";
+  /**
+   * Font size. Responsive object syntax supported. Default: "md"
+   */
+  size?: ListSize | Partial<Record<Breakpoints, ListSize>>;
+  /** Text colour. Default: "default" */
+  color?: "default" | "muted";
+  /**
+   * Material Symbols icon name applied to all list items.
+   * Setting `icon` automatically switches `variant` to "icon".
+   */
+  icon?: string | null;
+  /**
+   * List style. Auto-detected from `as` and `icon` when not set.
+   * "divider" renders items separated by horizontal rules.
+   */
+  variant?: "unordered" | "ordered" | "icon" | "divider";
+  /** Bottom margin. */
+  marginBottom?: "sm" | "md" | "lg";
+  children?: React.ReactNode;
+}
+
+export interface ListItemProps extends React.LiHTMLAttributes<HTMLLIElement> {
+  /**
+   * Per-item icon override. Pass `null` to suppress the list-level icon for this item.
+   * Omit to inherit from the parent `List`.
+   */
+  icon?: string | null;
+  children?: React.ReactNode;
+}
+
+export declare function List(props: ListProps): React.ReactElement;
+export declare function ListItem(props: ListItemProps): React.ReactElement;

package/src/components/menu/Menu.d.ts

@@ -0,0 +1,41 @@
+import * as React from "react";
+
+export interface MenuProps {
+  /** Whether the menu is open */
+  open: boolean;
+  /** Called when the menu should close */
+  onClose?: () => void;
+  /** Ref to the trigger element — used to position the menu below it */
+  anchorRef?: React.RefObject<HTMLElement>;
+  /** Accessible label for the menu `dialog` element */
+  "aria-label"?: string;
+  /** Additional CSS class names for the menu dialog */
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export interface MenuSectionProps {
+  /** Optional section label shown above the items */
+  label?: string;
+  children?: React.ReactNode;
+}
+
+export interface MenuItemProps extends React.HTMLAttributes<HTMLElement> {
+  /** Material Symbols icon name shown before the label */
+  icon?: string;
+  /** Keyboard shortcut hint displayed at the trailing end */
+  shortcut?: string;
+  /** Visual style. Default: "default" */
+  variant?: "default" | "destructive";
+  /** Marks this item as the current page. Adds a left-border indicator and aria-current="page". */
+  active?: boolean;
+  disabled?: boolean;
+  /** Renders as an anchor `<a>` when provided */
+  href?: string;
+  onClick?: React.MouseEventHandler;
+  children?: React.ReactNode;
+}
+
+export declare function Menu(props: MenuProps): React.ReactElement;
+export declare function MenuSection(props: MenuSectionProps): React.ReactElement;
+export declare function MenuItem(props: MenuItemProps): React.ReactElement;

package/src/components/message/Message.d.ts

@@ -0,0 +1,34 @@
+import * as React from "react";
+
+export interface MessageBadgeProps {
+  /** Semantic status colour. Default: "neutral" */
+  status?: "neutral" | "info" | "success" | "warn" | "error";
+  /** Reduce background opacity for a softer appearance. Default: false */
+  subtle?: boolean;
+  /** Size. Default: "md" */
+  size?: "sm" | "md" | "lg";
+  /**
+   * Override the default status icon. Pass `null` to suppress the icon entirely.
+   */
+  icon?: string | null;
+  children?: React.ReactNode;
+}
+
+export interface MessageEmptyStateProps {
+  /**
+   * Visual scale — matches the container this empty state lives in. Default: "section"
+   * page = largest (h1), section = medium (h2), card = compact (h3)
+   */
+  scale?: "page" | "section" | "card";
+  /** Material Symbols icon name shown above the title. Default: "inbox" */
+  icon?: string;
+  /** Primary message */
+  title?: string;
+  /** Supporting description text */
+  description?: string;
+  /** Action element (e.g. a Button) */
+  action?: React.ReactNode;
+}
+
+export declare function MessageBadge(props: MessageBadgeProps): React.ReactElement;
+export declare function MessageEmptyState(props: MessageEmptyStateProps): React.ReactElement;

package/src/components/notification/Notification.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+
+export interface NotificationProps {
+  /** Element the badge is anchored to */
+  children?: React.ReactNode;
+  /** Numeric count displayed in the badge */
+  count?: number;
+  /** Short text label — used when count is not set */
+  label?: string;
+  /** Show a dot with no content. Default: false */
+  dot?: boolean;
+  /**
+   * Visual status colour. Default: "neutral"
+   * neutral | error | success | warn | info
+   */
+  status?: "neutral" | "error" | "success" | "warn" | "info";
+  /** Badge anchor position. Default: "top-right" */
+  position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  /** Count above this value shows as {max}+. Default: 99 */
+  max?: number;
+}
+
+export declare function Notification(props: NotificationProps): React.ReactElement;

package/src/components/page-layout/PageLayout.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+
+export interface PageLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Top header slot — rendered in a `<header>` landmark */
+  header?: React.ReactNode;
+  /** Bottom footer slot — rendered in a `<footer>` landmark */
+  footer?: React.ReactNode;
+  /** Side navigation panel — rendered in an `<aside>` landmark */
+  sidebar?: React.ReactNode;
+  /** Which side the sidebar occupies. Default: "start" */
+  sidebarPlacement?: "start" | "end";
+  /** Supplemental content panel (e.g. a table of contents) */
+  aside?: React.ReactNode;
+  /** Which side the aside occupies. Default: "end" */
+  asidePlacement?: "start" | "end";
+  /** Keep the header fixed at the top while content scrolls. Default: false */
+  stickyHeader?: boolean;
+  /** Constrain the layout to 100vh. Default: false */
+  viewportHeight?: boolean;
+  /** Main content */
+  children?: React.ReactNode;
+}
+
+export declare function PageLayout(props: PageLayoutProps): React.ReactElement;