@tonycodes-ui/mortar 0.0.0-stage → 0.11.0

package/src/foundation.tsx

@@ -0,0 +1,227 @@
+import { NavigationContext, type Navigate } from "./navigation.js";
+import { SegmentedControl } from "./inspection.js";
+import {
+  AsComponentRoot,
+  ThemeScopeContext,
+  componentRoot,
+} from "./internal.js";
+import { Portal } from "@headlessui/react";
+import { brandToCss, type BrandDefinition } from "./brand.js";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+
+export type Appearance = "light" | "dark" | "system";
+/**
+ * A built-in brand, or the name of one declared in CSS
+ * (`[data-mortar-brand="name"]`) or through ThemeProvider's `brandTokens`.
+ */
+export type Brand = "neutral" | "green" | (string & {});
+export type Density = "compact" | "comfortable" | "spacious";
+type Theme = {
+  appearance: Appearance;
+  setAppearance: (value: Appearance) => void;
+  brand: Brand;
+  density: Density;
+};
+const ThemeContext = createContext<Theme | null>(null);
+export interface ThemeProviderProps {
+  children: ReactNode;
+  initialAppearance?: Appearance;
+  appearance?: Appearance;
+  onAppearanceChange?: (value: Appearance) => void;
+  /** Connect the application router once for every kit link. A nested provider without it keeps the outer router. */
+  navigate?: Navigate;
+  brand?: Brand;
+  /**
+   * Defines `brand` at runtime from data instead of CSS, e.g. a tenant's
+   * colours. Rendered as a `<style>` beside the provider's content (and
+   * server-rendered); overlays opened inside the provider share it.
+   * Omitted values derive from `primary`.
+   */
+  brandTokens?: BrandDefinition;
+  density?: Density;
+  /**
+   * document writes the root element. container paints a wrapper and leaves
+   * the document unchanged; menus, listboxes and dialogs opened inside it keep
+   * its theme.
+   */
+  scope?: "document" | "container";
+  /** On the container wrapper (container scope only). */
+  className?: string;
+}
+const DARK = "(prefers-color-scheme: dark)";
+function subscribeToScheme(update: () => void) {
+  const media = window.matchMedia(DARK);
+  media.addEventListener("change", update);
+  return () => media.removeEventListener("change", update);
+}
+/**
+ * The system colour scheme. The server snapshot is light, and React hydrates
+ * with it before switching to the real value, so markup always matches.
+ */
+function useSystemDark() {
+  return useSyncExternalStore(
+    subscribeToScheme,
+    () => window.matchMedia(DARK).matches,
+    () => false,
+  );
+}
+/**
+ * A body-level element that receives the container's overlays (menus,
+ * listboxes, popovers) so they keep its theme without being clipped by it.
+ */
+function usePortalHost(enabled: boolean, attributes: Record<string, string>) {
+  // Created during the first client render so portals can target it at once.
+  const [target] = useState(() => ({
+    current:
+      typeof document === "undefined" ? null : document.createElement("div"),
+  }));
+  const host = target.current;
+  useLayoutEffect(() => {
+    if (!host || !enabled) return;
+    host.className = "m-theme-scope";
+    for (const [key, value] of Object.entries(attributes))
+      host.setAttribute(key, value);
+  });
+  // Headless UI attaches the host when an overlay opens; remove it with us.
+  useEffect(() => () => host?.remove(), [host]);
+  return target;
+}
+/** One provider per application. Selection never requires a hosted account. */
+export function ThemeProvider({
+  children,
+  initialAppearance = "system",
+  appearance: controlledAppearance,
+  onAppearanceChange,
+  navigate,
+  brand = "neutral",
+  brandTokens,
+  density = "comfortable",
+  scope = "document",
+  className,
+}: ThemeProviderProps) {
+  const [localAppearance, setLocalAppearance] =
+    useState<Appearance>(initialAppearance);
+  const appearance = controlledAppearance ?? localAppearance;
+  const setAppearance = (value: Appearance) => {
+    setLocalAppearance(value);
+    onAppearanceChange?.(value);
+  };
+  const systemDark = useSystemDark();
+  const outerNavigate = useContext(NavigationContext);
+  const resolvedAppearance = (
+    appearance === "system" ? (systemDark ? "dark" : "light") : appearance
+  ) as "light" | "dark";
+  const attributes = {
+    "data-mortar": "",
+    "data-mortar-brand": brand,
+    "data-mortar-density": density,
+    "data-mortar-appearance": resolvedAppearance,
+  };
+  const host = usePortalHost(scope === "container", attributes);
+  useEffect(() => {
+    if (scope !== "document") return;
+    const element = document.documentElement;
+    const attributes = {
+      "data-mortar": "",
+      "data-mortar-brand": brand,
+      "data-mortar-density": density,
+    };
+    const previous = Object.keys(attributes).map(
+      (key) => [key, element.getAttribute(key)] as const,
+    );
+    for (const [key, value] of Object.entries(attributes))
+      element.setAttribute(key, value);
+    return () => {
+      for (const [key, value] of previous)
+        value === null
+          ? element.removeAttribute(key)
+          : element.setAttribute(key, value);
+    };
+  }, [brand, density, scope]);
+  useEffect(() => {
+    if (scope !== "document") return;
+    const element = document.documentElement;
+    const previous = element.getAttribute("data-mortar-appearance");
+    element.setAttribute("data-mortar-appearance", resolvedAppearance);
+    return () => {
+      previous === null
+        ? element.removeAttribute("data-mortar-appearance")
+        : element.setAttribute("data-mortar-appearance", previous);
+    };
+  }, [resolvedAppearance, scope]);
+  const brandCss = brandTokens ? brandToCss(brand, brandTokens) : undefined;
+  const theme = (
+    <NavigationContext.Provider value={navigate ?? outerNavigate}>
+      {brandCss && (
+        // An ordinary element, not a hoisted resource: React updates its
+        // content when the tokens change and removes it on unmount, and it
+        // is server-rendered. The rule keys on the brand attribute, so
+        // portalled overlays match it wherever they render.
+        <style data-mortar-brand-style={brand}>{brandCss}</style>
+      )}
+      <ThemeContext.Provider
+        value={{ appearance, setAppearance, brand, density }}
+      >
+        {children}
+      </ThemeContext.Provider>
+    </NavigationContext.Provider>
+  );
+  if (scope === "container")
+    return (
+      <div
+        {...componentRoot("ThemeProvider")}
+        {...attributes}
+        className={className}
+      >
+        <ThemeScopeContext.Provider value={attributes}>
+          <Portal.Group target={host}>{theme}</Portal.Group>
+        </ThemeScopeContext.Provider>
+      </div>
+    );
+  return theme;
+}
+export function AppearanceControl({
+  value,
+  onChange,
+  className,
+}: {
+  value?: Appearance;
+  onChange?: (value: Appearance) => void;
+  className?: string;
+} = {}) {
+  const controlled = value !== undefined || onChange !== undefined;
+  if ((value === undefined) !== (onChange === undefined))
+    throw new Error(
+      "AppearanceControl requires both value and onChange, or neither.",
+    );
+  const context = useContext(ThemeContext);
+  if (!controlled && !context)
+    throw new Error("AppearanceControl requires ThemeProvider");
+  const appearance = controlled ? value : context!.appearance;
+  const select = (next: Appearance) => {
+    if (controlled) onChange?.(next);
+    else context!.setAppearance(next);
+  };
+  return (
+    <AsComponentRoot name="AppearanceControl" of="SegmentedControl">
+      <SegmentedControl
+        label="Appearance"
+        value={appearance!}
+        className={className}
+        options={(["light", "dark", "system"] as const).map((option) => ({
+          value: option,
+          label: option[0].toUpperCase() + option.slice(1),
+        }))}
+        onChange={(next) => select(next as Appearance)}
+      />
+    </AsComponentRoot>
+  );
+}

package/src/heading.ts

@@ -0,0 +1,13 @@
+// Shared heading-level helpers. Internal: not exported from the package entry.
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/** The heading element for a level, e.g. `headingTag(2)` is `"h2"`. */
+export function headingTag<L extends HeadingLevel>(level: L) {
+  return `h${level}` as `h${L}`;
+}
+
+/** The level for headings nested under `level`, capped at `max` (default h6). */
+export function childLevel(level: HeadingLevel, max: HeadingLevel = 6) {
+  return Math.min(level + 1, max) as HeadingLevel;
+}

package/src/icons.tsx

@@ -0,0 +1,237 @@
+// Shared decorative icons. Internal: not exported from the package entry.
+import type { ReactNode } from "react";
+
+/**
+ * Decorative SVG on the 20×20 grid. Hidden from assistive technology unless
+ * `decorative` is false; meaning is carried by surrounding text.
+ */
+export function Icon({
+  className,
+  viewBox = "0 0 20 20",
+  fill = "none",
+  stroke,
+  strokeWidth,
+  decorative = true,
+  focusable = false,
+  children,
+}: {
+  className?: string;
+  viewBox?: string;
+  /** SVG fill; `null` omits the attribute (paths set their own). */
+  fill?: string | null;
+  stroke?: string;
+  strokeWidth?: string;
+  /** Adds aria-hidden="true". */
+  decorative?: boolean;
+  /** Keep the SVG out of the tab order (focusable="false"); `true` omits the attribute. */
+  focusable?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <svg
+      className={className}
+      viewBox={viewBox}
+      fill={fill ?? undefined}
+      stroke={stroke}
+      strokeWidth={strokeWidth}
+      aria-hidden={decorative ? "true" : undefined}
+      focusable={decorative && !focusable ? "false" : undefined}
+    >
+      {children}
+    </svg>
+  );
+}
+
+/** Round-capped currentColor stroke. */
+function Stroke({
+  d,
+  width,
+  fill,
+  join = true,
+}: {
+  d: string;
+  width: string;
+  fill?: string;
+  /** Round line joins; the close glyph has none. */
+  join?: boolean;
+}) {
+  return (
+    <path
+      d={d}
+      fill={fill}
+      stroke="currentColor"
+      strokeWidth={width}
+      strokeLinecap="round"
+      strokeLinejoin={join ? "round" : undefined}
+    />
+  );
+}
+
+export function ChevronDown() {
+  return (
+    <Icon>
+      <Stroke d="m6 8 4 4 4-4" width="1.5" />
+    </Icon>
+  );
+}
+
+export function ChevronLeft() {
+  return (
+    <Icon>
+      <Stroke d="m12 5-5 5 5 5" width="1.75" />
+    </Icon>
+  );
+}
+
+export function ChevronRight() {
+  return (
+    <Icon>
+      <Stroke d="m8 5 5 5-5 5" width="1.75" />
+    </Icon>
+  );
+}
+
+/**
+ * Check mark. The three call sites predate this module and differ:
+ * `option` (listbox/combobox selected option), `list` (CheckList, 16×16 grid,
+ * fill on the path) and `step` (ProgressSteps circles: stroke on the svg,
+ * heavier weight, not aria-hidden because its marker span already is).
+ */
+export function Check({
+  variant = "option",
+  className,
+}: {
+  variant?: "option" | "list" | "step";
+  className?: string;
+}) {
+  if (variant === "list")
+    return (
+      <Icon viewBox="0 0 16 16" fill={null}>
+        <Stroke d="M3.5 8.5 6.5 11.5 12.5 4.5" width="1.75" fill="none" />
+      </Icon>
+    );
+  if (variant === "step")
+    return (
+      <Icon stroke="currentColor" strokeWidth="2.5" decorative={false}>
+        <path
+          d="M5 10.5l3.5 3.5L15 7"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </Icon>
+    );
+  return (
+    <Icon className={className}>
+      <Stroke d="m5 10 3.5 3.5L15 7" width="1.75" />
+    </Icon>
+  );
+}
+
+export function Close() {
+  return (
+    <Icon>
+      <Stroke d="m5 5 10 10M15 5 5 15" width="1.75" join={false} />
+    </Icon>
+  );
+}
+
+export function ArrowUp() {
+  return (
+    <Icon>
+      <Stroke d="M10 15V5m0 0-4 4m4-4 4 4" width="1.75" />
+    </Icon>
+  );
+}
+
+export function ArrowDown() {
+  return (
+    <Icon>
+      <Stroke d="M10 5v10m0 0-4-4m4 4 4-4" width="1.75" />
+    </Icon>
+  );
+}
+
+export function Star() {
+  return (
+    <Icon fill={null}>
+      <path
+        d="M10 1.8l2.5 5.3 5.8.7-4.3 4 1.1 5.7L10 14.7l-5.1 2.8 1.1-5.7-4.3-4 5.8-.7z"
+        fill="currentColor"
+      />
+    </Icon>
+  );
+}
+
+export function Paperclip() {
+  return (
+    <Icon>
+      <Stroke
+        d="M7 10.5l5-5a2.5 2.5 0 0 1 3.5 3.5l-6.5 6.5a4 4 0 0 1-5.7-5.7l6.2-6.2"
+        width="1.5"
+      />
+    </Icon>
+  );
+}
+
+/** Generic person silhouette for avatars without a photo (24×24 grid, filled). */
+export function Person({ className }: { className?: string }) {
+  return (
+    <Icon
+      className={className}
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      focusable
+    >
+      <path d="M24 20.993V24H0v-2.996A14.977 14.977 0 0 1 12.004 15c4.904 0 9.26 2.354 11.996 5.993zM16.002 8.999a4 4 0 1 1-8 0 4 4 0 0 1 8 0z" />
+    </Icon>
+  );
+}
+
+/** Table sort indicator; the active direction's chevron is marked data-active. */
+export function SortArrows({
+  direction,
+}: {
+  direction?: "ascending" | "descending";
+}) {
+  return (
+    <Icon viewBox="0 0 12 12" fill={null}>
+      <path
+        d="M3.5 4.5 6 2l2.5 2.5"
+        data-active={direction === "ascending" || undefined}
+      />
+      <path
+        d="M3.5 7.5 6 10l2.5-2.5"
+        data-active={direction === "descending" || undefined}
+      />
+    </Icon>
+  );
+}
+
+const EYE =
+  "M1.75 10S4.75 4.25 10 4.25 18.25 10 18.25 10 15.25 15.75 10 15.75 1.75 10 1.75 10zM10 12.5a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5z";
+/** Open eye: shown while a password is hidden. */
+export function Eye() {
+  return (
+    <Icon>
+      <Stroke d={EYE} width="1.5" />
+    </Icon>
+  );
+}
+
+/** Struck-through eye: shown while a password is visible. */
+export function EyeOff() {
+  return (
+    <Icon>
+      <Stroke d={EYE + "M3 3l14 14"} width="1.5" />
+    </Icon>
+  );
+}
+
+/** Hollow circle: a requirement that is not met yet. */
+export function Circle() {
+  return (
+    <Icon>
+      <Stroke d="M10 15a5 5 0 1 0 0-10 5 5 0 0 0 0 10z" width="1.5" />
+    </Icon>
+  );
+}

package/src/index.ts

@@ -0,0 +1,230 @@
+export { ThemeProvider, AppearanceControl } from "./foundation.js";
+export type { BrandDefinition, BrandAppearanceTokens } from "./brand.js";
+export type {
+  ThemeProviderProps,
+  Appearance,
+  Brand,
+  Density,
+} from "./foundation.js";
+export {
+  Button,
+  ButtonGroup,
+  ActionLink,
+  Input,
+  Select,
+  TextArea,
+  Checkbox,
+  Fieldset,
+  RadioGroup,
+  Switch,
+  Badge,
+  Tabs,
+  Modal,
+  Dropdown,
+  Notice,
+  EmptyState,
+  ErrorSummary,
+} from "./primitives.js";
+export type {
+  ButtonProps,
+  ButtonGroupItem,
+  DropdownItem,
+  ErrorSummaryItem,
+  InputProps,
+  LinkAction,
+  Tone,
+} from "./primitives.js";
+export {
+  AppShell,
+  PageHeading,
+  MetricGroup,
+  DataTable,
+  Table,
+  Pagination,
+  SettingsSection,
+  ActivityFeed,
+  SignInPanel,
+  Sidebar,
+  Navbar,
+  StackedShell,
+  Breadcrumbs,
+  ProgressSteps,
+  TabNav,
+  ActionPanel,
+} from "./application.js";
+export type {
+  AppShellProps,
+  NavigationItem,
+  DataTableProps,
+  DataTableColumn,
+  TableSort,
+  SortDirection,
+  SignInProvider,
+  SidebarProps,
+  BreadcrumbItem,
+  ProgressStep,
+  TabNavItem,
+  StackedShellProps,
+  NavbarProps,
+  BreadcrumbsProps,
+  TabNavProps,
+  ProgressStepsProps,
+  ActionPanelProps,
+  PageHeadingProps,
+  MetricGroupProps,
+  TableProps,
+  PaginationProps,
+  SettingsSectionProps,
+  ActivityFeedProps,
+  SignInPanelProps,
+} from "./application.js";
+export {
+  AuthLayout,
+  ProviderButtons,
+  PasswordInput,
+  CodeInput,
+} from "./auth.js";
+export type {
+  AuthLayoutProps,
+  ProviderButtonsProps,
+  PasswordInputProps,
+  PasswordRequirement,
+  PasswordStrength,
+  CodeInputProps,
+} from "./auth.js";
+export {
+  MarketingHeader,
+  Hero,
+  FeatureGrid,
+  FeatureSection,
+  ProcessSteps,
+  Testimonial,
+  LogoCloud,
+  Pricing,
+  FAQ,
+  CallToAction,
+  Footer,
+  HeaderSection,
+  ContentSection,
+} from "./marketing.js";
+export type {
+  PricingPlan,
+  PricingExtra,
+  HeaderLink,
+  FlyoutItem,
+} from "./marketing.js";
+export { SegmentedControl, CodeBlock, PreviewFrame } from "./inspection.js";
+export {
+  Avatar,
+  AvatarGroup,
+  Kbd,
+  ProgressBar,
+  FilterChip,
+  CheckList,
+  DescriptionList,
+  GridList,
+  AttachmentList,
+} from "./display.js";
+export type {
+  GridListItem,
+  Attachment,
+  AvatarProps,
+  AvatarGroupProps,
+  KbdProps,
+  ProgressBarProps,
+  FilterChipProps,
+  CheckListProps,
+  DescriptionListProps,
+  GridListProps,
+  AttachmentListProps,
+} from "./display.js";
+export {
+  Stack,
+  Container,
+  Text,
+  Section,
+  Divider,
+  Card,
+  MediaObject,
+  SectionHeading,
+  Prose,
+} from "./layout.js";
+export type {
+  SectionTone,
+  StackProps,
+  ContainerProps,
+  TextProps,
+  SectionProps,
+  DividerProps,
+  CardProps,
+  MediaObjectProps,
+  SectionHeadingProps,
+  ProseProps,
+} from "./layout.js";
+export { MockWindow, ChatPreview } from "./showcase.js";
+export type { ChatMessage } from "./showcase.js";
+export { Toast, Toaster, ConfirmDialog, SaveBar, Banner } from "./feedback.js";
+export type { ToastItem, ToastAction } from "./feedback.js";
+export { SlideOver, CommandPalette, StackedList } from "./workspace.js";
+export type {
+  CommandItem,
+  StackedListItem,
+  SlideOverProps,
+  CommandPaletteProps,
+  StackedListProps,
+} from "./workspace.js";
+export {
+  BentoGrid,
+  StatGroup,
+  TestimonialGrid,
+  PlanComparison,
+  PostList,
+  TeamGrid,
+  ContactSection,
+  Newsletter,
+  NotFound,
+} from "./marketing-sections.js";
+export {
+  DocsShell,
+  SearchTrigger,
+  SearchDialog,
+  Steps,
+  Callout,
+  FileTree,
+  CodeTabs,
+  Release,
+  ApiEndpoint,
+  PageFeedback,
+  PagerLinks,
+  LinkCards,
+} from "./docs.js";
+export type { DocsShellProps, FileNode } from "./docs.js";
+export { Listbox, Combobox } from "./choice.js";
+export type { ChoiceOption } from "./choice.js";
+export { Calendar } from "./calendar.js";
+export type { CalendarEvent, CalendarView, CalendarProps } from "./calendar.js";
+export {
+  ProductList,
+  ProductOverview,
+  ShoppingCart,
+  OrderSummary,
+  ProductQuickView,
+  ProductFilters,
+  ProductReviews,
+  OrderHistory,
+} from "./ecommerce.js";
+export type {
+  ProductImage,
+  ProductCard,
+  ProductOption,
+  CartItem,
+  FilterFacet,
+  Review,
+  Order,
+  ProductListProps,
+  ProductOverviewProps,
+  ShoppingCartProps,
+} from "./ecommerce.js";
+export { CommentComposer } from "./composer.js";
+export type { LinkItem, ItemGroup } from "./navigation.js";
+export type { HeadingLevel } from "./heading.js";