@sovereignfs/ui 0.21.0

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, InputHTMLAttributes, HTMLAttributes } from 'react';
+
+type BadgeVariant = 'role' | 'status' | 'mono';
+type BadgeStatus = 'active' | 'enabled' | 'deactivated' | 'failed' | 'invited' | 'pending' | 'neutral';
+interface BadgeProps {
+    variant?: BadgeVariant;
+    /** Only relevant when variant="status" — determines the dot colour. */
+    status?: BadgeStatus;
+    children: ReactNode;
+}
+/**
+ * Badge — compact label for roles, lifecycle states, and type/version tags.
+ *
+ * - `role`   neutral surface + border, semibold — for Owner / Admin / User
+ * - `status` tinted chip with leading colour dot — for Active / Deactivated / etc.
+ * - `mono`   monospace font, neutral surface — for platform / community / v0.1.0
+ */
+declare function Badge({ variant, status, children }: BadgeProps): react.JSX.Element;
+
+type IconName = 'house' | 'settings' | 'log-out' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'user' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'mail' | 'bell' | 'activity' | 'package' | 'grid-2x2' | 'info' | 'alert-triangle' | 'sliders-horizontal' | 'terminal';
+
+/** Decorative icon — visually meaningful but described by surrounding text. */
+type DecorativeProps = {
+    'aria-hidden': true;
+    'aria-label'?: never;
+};
+/** Meaningful icon — standalone affordance that requires a label for screen readers. */
+type MeaningfulProps = {
+    'aria-label': string;
+    'aria-hidden'?: never;
+};
+interface IconProps {
+    /** Name of the icon from the curated Sovereign set. */
+    name: IconName;
+    /** Visual size. Defaults to `"md"` (20 px). */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS class applied to the SVG element. */
+    className?: string;
+}
+/**
+ * `<Icon>` — the Sovereign design system icon primitive.
+ *
+ * Icons are either **decorative** (described by surrounding text — pass `aria-hidden`)
+ * or **meaningful** (standalone affordance — pass `aria-label`):
+ *
+ * ```tsx
+ * <Icon name="house" aria-hidden />           // decorative
+ * <Icon name="log-out" aria-label="Sign out" /> // meaningful
+ * ```
+ *
+ * Color follows `currentColor` so an icon automatically inherits the text color
+ * of its container and recolors with theme changes — no extra CSS required.
+ */
+declare function Icon({ name, size, className, ...aria }: IconProps & (DecorativeProps | MeaningfulProps)): react.JSX.Element;
+
+interface ToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onChange' | 'aria-label'> {
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    disabled?: boolean;
+    'aria-label': string;
+}
+/**
+ * Toggle — 38×22px binary switch for settings rows.
+ *
+ * Renders as `<button role="switch">` rather than a hidden `<input type="checkbox">`
+ * to avoid iOS VoiceOver focus quirks on visually styled checkboxes. The `aria-label`
+ * prop is required because the control has no visible text label of its own.
+ */
+declare function Toggle({ checked, onChange, disabled, className, ...rest }: ToggleProps): react.JSX.Element;
+
+interface SegmentedOption<T extends string = string> {
+    label: string;
+    value: T;
+}
+interface SegmentedControlProps<T extends string = string> {
+    value: T;
+    onChange: (value: T) => void;
+    options: SegmentedOption<T>[];
+    size?: 'sm' | 'md';
+    'aria-label': string;
+}
+/**
+ * SegmentedControl — pill-based 2–3 option picker for inline use in table rows
+ * and dialogs (e.g. User / Admin / Owner role switcher).
+ *
+ * Renders as `<div role="radiogroup">` with `<button role="radio">` children —
+ * correct semantics without a native `<input type="radio">` (which needs an id/name
+ * pair and a `<form>` context to function correctly in all browsers).
+ */
+declare function SegmentedControl<T extends string = string>({ value, onChange, options, size, 'aria-label': ariaLabel, }: SegmentedControlProps<T>): react.JSX.Element;
+
+interface TabItem {
+    label: string;
+    value: string;
+}
+interface TabsProps {
+    items: TabItem[];
+    value: string;
+    onChange: (value: string) => void;
+    'aria-label': string;
+}
+/**
+ * Tabs — underline tab nav for section switching.
+ *
+ * Stateless: the active tab is fully controlled via `value` + `onChange`, so the
+ * caller owns state and controls the rendered panel content. This keeps the
+ * component RSC-compatible when wrapped by a client boundary upstream.
+ *
+ * Mobile: the tab bar scrolls horizontally with the native scrollbar hidden.
+ */
+declare function Tabs({ items, value, onChange, 'aria-label': ariaLabel }: TabsProps): react.JSX.Element;
+
+type SelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> & {
+    /** 'md' (default) — standard form field height. 'sm' — compact for table cells and inline controls. */
+    size?: 'sm' | 'md';
+};
+/**
+ * Select — styled wrapper around the native `<select>`. Inherits the same
+ * height, border, radius, and focus ring as `Input` for visual consistency.
+ * Uses the native picker on mobile — no custom dropdown, maximum a11y coverage.
+ *
+ * RSC-safe: presentational, no hooks, forwards all native select props.
+ */
+declare function Select({ className, size, children, ...rest }: SelectProps): react.JSX.Element;
+
+type BannerVariant = 'info' | 'warning' | 'error';
+interface SystemBannerProps {
+    variant?: BannerVariant;
+    /** Called when the user clicks ×. If omitted, no dismiss button is shown. */
+    onDismiss?: () => void;
+    children: ReactNode;
+}
+/**
+ * SystemBanner — full-width sticky strip that shifts page content down.
+ *
+ * Used for platform-level notices: maintenance mode, license warnings, broadcast
+ * messages. Stack multiple banners by rendering multiple `<SystemBanner>` elements.
+ * The dismiss button is only rendered when `onDismiss` is provided.
+ */
+declare function SystemBanner({ variant, onDismiss, children }: SystemBannerProps): react.JSX.Element;
+
+interface PopoverProps {
+    /** The element that opens the popover — rendered as-is; caller wires its onClick. */
+    trigger: ReactElement;
+    open: boolean;
+    onClose: () => void;
+    /** Which edge of the trigger the panel aligns to. Default: 'right'. */
+    align?: 'left' | 'right';
+    /** Panel width in px. Default: 288. */
+    width?: number;
+    'aria-label': string;
+    children: ReactNode;
+}
+/**
+ * Popover — floating panel anchored below a trigger element.
+ *
+ * Positioning is `position: absolute` inside a `position: relative` wrapper —
+ * no floating-ui dependency. Supports left/right alignment against the trigger edge.
+ * Closes on outside click or Escape. Does not trap focus (it is non-modal).
+ */
+declare function Popover({ trigger, open, onClose, align, width, 'aria-label': ariaLabel, children, }: PopoverProps): react.JSX.Element;
+
+type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
+type ButtonSize = 'sm' | 'md';
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    children: ReactNode;
+}
+/**
+ * Button — the primitive interactive control. Presentational and RSC-safe: it
+ * holds no state and simply forwards props to the underlying `<button>`, so it
+ * renders in both Server and Client Components. All styling references `--sv-*`
+ * tokens via CSS Modules; there are no hardcoded values.
+ */
+declare function Button({ variant, size, type, className, children, ...rest }: ButtonProps): react.JSX.Element;
+
+type InputProps = InputHTMLAttributes<HTMLInputElement>;
+/**
+ * Input — the primitive text field. Presentational and RSC-safe: it forwards
+ * all native input props to the underlying `<input>`. Styling references
+ * `--sv-*` tokens via CSS Modules; there are no hardcoded values.
+ */
+declare function Input({ type, className, ...rest }: InputProps): react.JSX.Element;
+
+type DialogSize = 'sm' | 'md' | 'lg' | 'full';
+interface DialogProps {
+    /** Whether the dialog is shown. When false, nothing renders. */
+    open: boolean;
+    /** Called on Esc, scrim click, or the close button. */
+    onClose: () => void;
+    /** Panel size on desktop. Mobile always renders as a full-screen sheet. */
+    size?: DialogSize;
+    /** Accessible name for the dialog (sets `aria-label` on the panel). */
+    'aria-label'?: string;
+    /** On mobile: shown in the top bar alongside the close button so the title
+     *  and dismiss affordance occupy the same row instead of stacking. */
+    title?: string;
+    children: ReactNode;
+}
+/**
+ * Dialog — a modal surface (scrim + panel) for overlay-shell plugins and any
+ * plugin that needs a dismissable layer. Router-agnostic: the caller decides
+ * what `onClose` does (the runtime's `@modal` slot wires it to `router.back()`).
+ *
+ * Behaviour: Esc and scrim-click dismiss; focus moves into the panel on open and
+ * is restored to the previously-focused element on close; Tab is trapped within
+ * the panel. Styling references `--sv-*` tokens only; on mobile the panel becomes
+ * a full-screen sheet regardless of `size`.
+ */
+declare function Dialog({ open, onClose, size, 'aria-label': ariaLabel, title, children, }: DialogProps): react.JSX.Element | null;
+
+interface DrawerProps {
+    /** Whether the drawer is shown. When false, nothing renders. */
+    open: boolean;
+    /** Called on Esc or scrim click. */
+    onClose: () => void;
+    /** Accessible name for the drawer panel (sets `aria-label`). */
+    'aria-label'?: string;
+    children: ReactNode;
+}
+/**
+ * Drawer — a dismissable bottom-sheet panel. Used by the mobile shell for
+ * plugin navigation; also available to plugins for any bottom-up surface.
+ *
+ * Behaviour: Esc and scrim-click dismiss; focus moves to the first focusable
+ * element on open and is restored on close; Tab is trapped within the panel.
+ * The panel respects `env(safe-area-inset-bottom)` so it clears the home
+ * indicator in standalone/fullscreen mode. Shares dismissal conventions and
+ * tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with `Dialog`.
+ */
+declare function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: DrawerProps): react.JSX.Element | null;
+
+interface ToastItem {
+    id: string;
+    title: string;
+    message?: string;
+    /** `'info'` | `'success'` | `'warning'` | `'error'` | `'security'` | `'announcement'` */
+    category?: string;
+    /** Auto-dismiss delay in ms. Default 5000. Pass `0` to disable auto-dismiss. */
+    duration?: number;
+    exiting?: boolean;
+}
+interface ToastContextValue {
+    /** Show a toast notification. Returns the generated toast id. */
+    show(item: Omit<ToastItem, 'id'>): string;
+    /** Dismiss a toast by id. */
+    dismiss(id: string): void;
+}
+/** Consume the toast context to imperatively show toasts from any client component. */
+declare function useToast(): ToastContextValue;
+declare function ToastProvider({ children }: {
+    children: React.ReactNode;
+}): react.JSX.Element;
+
+interface CardProps extends HTMLAttributes<HTMLElement> {
+    as?: 'div' | 'article' | 'li';
+    interactive?: boolean;
+    padding?: 'sm' | 'md' | 'lg';
+    children: ReactNode;
+}
+declare function Card({ as: Tag, interactive, padding, className, children, ...rest }: CardProps): react.JSX.Element;
+
+interface FormFieldProps {
+    label: string;
+    hint?: string;
+    error?: string;
+    htmlFor?: string;
+    required?: boolean;
+    children: ReactNode;
+    className?: string;
+}
+declare function FormField({ label, hint, error, htmlFor, required, children, className, }: FormFieldProps): react.JSX.Element;
+
+interface PageHeaderProps {
+    title: string;
+    description?: string;
+    action?: ReactNode;
+    className?: string;
+}
+declare function PageHeader({ title, description, action, className }: PageHeaderProps): react.JSX.Element;
+
+interface EmptyStateProps {
+    icon?: IconName;
+    heading: string;
+    description?: string;
+    action?: ReactNode;
+    className?: string;
+}
+declare function EmptyState({ icon, heading, description, action, className }: EmptyStateProps): react.JSX.Element;
+
+interface SpinnerProps {
+    size?: 'sm' | 'md' | 'lg';
+    label?: string;
+    className?: string;
+}
+declare function Spinner({ size, label, className }: SpinnerProps): react.JSX.Element;
+
+interface AvatarProps {
+    name: string;
+    src?: string;
+    size?: 'sm' | 'md' | 'lg';
+    className?: string;
+}
+declare function Avatar({ name, src, size, className }: AvatarProps): react.JSX.Element;
+
+interface NavTabItem {
+    label: string;
+    href: string;
+    active?: boolean;
+}
+interface NavTabsProps {
+    items: NavTabItem[];
+    className?: string;
+    'aria-label'?: string;
+}
+declare function NavTabs({ items, className, 'aria-label': ariaLabel }: NavTabsProps): react.JSX.Element;
+
+interface TooltipProps {
+    content: string;
+    children: ReactElement;
+    side?: 'top' | 'bottom' | 'left' | 'right';
+}
+declare function Tooltip({ content, children, side }: TooltipProps): react.JSX.Element;
+
+export { Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, type BannerVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardProps, Dialog, type DialogProps, type DialogSize, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FormField, type FormFieldProps, Icon, type IconName, type IconProps, Input, type InputProps, type NavTabItem, NavTabs, type NavTabsProps, PageHeader, type PageHeaderProps, Popover, type PopoverProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Spinner, type SpinnerProps, SystemBanner, type SystemBannerProps, type TabItem, Tabs, type TabsProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, useToast };