sid-ui 0.0.0-stage → 0.1.0

package/src/components/Page.tsx

@@ -0,0 +1,143 @@
+import { Card } from "@astryxdesign/core/Card";
+import { Divider } from "@astryxdesign/core/Divider";
+import { Grid } from "@astryxdesign/core/Grid";
+import { HStack, Stack } from "@astryxdesign/core/Stack";
+import { Heading, Text } from "@astryxdesign/core/Text";
+
+import type { ReactNode } from "react";
+
+/**
+ * Page-level composites every Joined app shares: the centered content
+ * column, the page title row, a titled section card, and a row of stats.
+ * Built only from Astryx parts, so they follow the theme like everything else.
+ */
+
+export const PAGE_WIDTHS = { narrow: 720, default: 1200, wide: 1360 } as const;
+export type PageWidth = keyof typeof PAGE_WIDTHS;
+
+/** Centers a page's content at a shared reading width. */
+export function PageContainer({
+  children,
+  width = "default",
+}: {
+  children: ReactNode;
+  width?: PageWidth;
+}) {
+  return (
+    <Stack hAlign="center">
+      <Stack gap={6} maxWidth={PAGE_WIDTHS[width]} width="100%">
+        {children}
+      </Stack>
+    </Stack>
+  );
+}
+
+/** The title row: heading, a quiet description, and the page's main action. */
+export function PageHeader({
+  title,
+  description,
+  action,
+}: {
+  title: string;
+  description?: string;
+  action?: ReactNode;
+}) {
+  return (
+    <HStack hAlign="between" vAlign="end" wrap="wrap" gap={3}>
+      <Stack gap={1}>
+        <Heading level={1}>{title}</Heading>
+        {description ? (
+          <Text color="secondary" display="block">
+            {description}
+          </Text>
+        ) : null}
+      </Stack>
+      {action}
+    </HStack>
+  );
+}
+
+/** A titled card: heading, quiet description, optional action, then content. */
+export function SectionCard({
+  title,
+  description,
+  action,
+  footer,
+  children,
+}: {
+  title: string;
+  description?: string;
+  action?: ReactNode;
+  footer?: ReactNode;
+  children?: ReactNode;
+}) {
+  return (
+    <Card padding={6}>
+      <Stack gap={5}>
+        <HStack hAlign="between" vAlign="start" gap={3} wrap="wrap">
+          <Stack gap={1}>
+            <Heading level={2}>{title}</Heading>
+            {description ? (
+              <Text type="supporting" color="secondary" display="block">
+                {description}
+              </Text>
+            ) : null}
+          </Stack>
+          {action}
+        </HStack>
+        {children}
+        {footer ? (
+          <Stack gap={4}>
+            <Divider />
+            {footer}
+          </Stack>
+        ) : null}
+      </Stack>
+    </Card>
+  );
+}
+
+export type Stat = {
+  label: string;
+  value: string;
+  hint?: string;
+  accessory?: ReactNode;
+};
+
+/** One headline number with its label and a quiet hint. */
+export function StatCard({ label, value, hint, accessory }: Stat) {
+  return (
+    <Card padding={5}>
+      <Stack gap={2}>
+        <Text type="supporting" color="secondary" display="block">
+          {label}
+        </Text>
+        <HStack gap={2} vAlign="center" wrap="wrap">
+          <Heading level={2} type="display-3">
+            {value}
+          </Heading>
+          {accessory}
+        </HStack>
+        {hint ? (
+          <Text type="supporting" color="secondary" display="block">
+            {hint}
+          </Text>
+        ) : null}
+      </Stack>
+    </Card>
+  );
+}
+
+const STAT_MIN_WIDTH = 150;
+const STAT_MAX_COLUMNS = 4;
+
+/** Stats that wrap from four across to one as the page narrows. */
+export function StatGrid({ stats }: { stats: Stat[] }) {
+  return (
+    <Grid columns={{ minWidth: STAT_MIN_WIDTH, max: STAT_MAX_COLUMNS }} gap={4}>
+      {stats.map((stat) => (
+        <StatCard key={stat.label} {...stat} />
+      ))}
+    </Grid>
+  );
+}

package/src/components/PageTabs.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { Tab, TabList } from "./Navigation";
+
+export type PageTab = { value: string; label: string; href: string };
+
+/**
+ * Tabs that switch a page's view by navigating (each tab is a link), so the view is
+ * server-rendered and shareable. Pass the current tab's `value`.
+ */
+export function PageTabs({
+  tabs,
+  value,
+  label,
+}: {
+  tabs: PageTab[];
+  value: string;
+  /** Names the tab group for screen readers. */
+  label?: string;
+}) {
+  return (
+    <TabList value={value} onChange={() => {}} hasDivider overflow="scroll" aria-label={label}>
+      {tabs.map((tab) => (
+        <Tab key={tab.value} value={tab.value} label={tab.label} href={tab.href} />
+      ))}
+    </TabList>
+  );
+}

package/src/components/PickerShell.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+
+import { IconButton } from "./Action";
+import { icons, type GlyphName } from "./Glyph";
+import { useDismiss } from "./hooks";
+import { Icon } from "./Primitives";
+
+import type { ControlSize } from "./size";
+
+export interface PickerShellProps {
+  /** Typed segments rendered inside the control. */
+  segments: ReactNode;
+  /** The dropdown panel. Omit for a type-only field. */
+  panel?: ReactNode;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  icon: GlyphName;
+  /** Accessible name for the segments group and the panel. */
+  label: string;
+  labelledBy?: string;
+  size?: ControlSize;
+  error?: boolean;
+  disabled?: boolean;
+}
+
+/** Space between the field and its panel, in px. */
+const PANEL_GAP = 8;
+
+/**
+ * The shared chrome for typed date and time fields: an Input-shaped control
+ * that you can type into, plus a trigger that drops a picker panel below it.
+ */
+export function PickerShell({
+  segments,
+  panel,
+  open,
+  onOpenChange,
+  icon,
+  label,
+  labelledBy,
+  size = "md",
+  error,
+  disabled,
+}: PickerShellProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const controlRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [position, setPosition] = useState<CSSProperties | null>(null);
+  const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+  useDismiss(rootRef, open, close);
+
+  // Fixed positioning escapes cards that clip overflow; flip above when below is short.
+  useLayoutEffect(() => {
+    if (!open) {
+      setPosition(null);
+      return;
+    }
+    function place() {
+      const field = controlRef.current?.getBoundingClientRect();
+      const height = panelRef.current?.offsetHeight ?? 0;
+      if (!field) return;
+      const below = window.innerHeight - field.bottom - PANEL_GAP;
+      const flip = height > below && field.top > below;
+      setPosition({
+        left: field.left,
+        top: flip ? field.top - PANEL_GAP - height : field.bottom + PANEL_GAP,
+      });
+    }
+    place();
+    window.addEventListener("scroll", place, true);
+    window.addEventListener("resize", place);
+    return () => {
+      window.removeEventListener("scroll", place, true);
+      window.removeEventListener("resize", place);
+    };
+  }, [open]);
+
+  const shell = [
+    "os-control",
+    `os-control-${size}`,
+    "os-picker-control",
+    error && "os-control-error",
+    disabled && "os-control-disabled",
+    open && "os-picker-control-open",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div ref={rootRef} className="os-picker">
+      <div ref={controlRef} className={shell}>
+        <div
+          className="os-segments"
+          role="group"
+          aria-label={labelledBy ? undefined : label}
+          aria-labelledby={labelledBy}
+        >
+          {segments}
+        </div>
+        {panel && (
+          <IconButton
+            className="os-picker-trigger"
+            label={
+              open ? `Close ${label.toLowerCase()} picker` : `Open ${label.toLowerCase()} picker`
+            }
+            aria-expanded={open}
+            aria-haspopup="dialog"
+            variant="ghost"
+            size="sm"
+            isDisabled={disabled}
+            icon={<Icon icon={icons[icon]} />}
+            onClick={() => onOpenChange(!open)}
+          />
+        )}
+      </div>
+      {panel && open && (
+        <div
+          ref={panelRef}
+          className="os-picker-panel"
+          role="dialog"
+          aria-label={label}
+          style={position ?? { visibility: "hidden" }}
+        >
+          {panel}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/PillNav.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+import { useLinkComponent } from "@astryxdesign/core/Link";
+import { Tooltip } from "@astryxdesign/core/Tooltip";
+import { useLayoutEffect, useRef, useState, type MouseEvent, type RefObject } from "react";
+
+import { Glyph, type GlyphName } from "./Glyph";
+import { lerpBox, parseDuration, parseEasing, type Box } from "./motion";
+
+/** Larger counts read as "99+" so the bubble stays small. */
+const MAX_COUNT = 99;
+/** The theme tokens the sliding highlight moves with, so it lands together with the CSS label. */
+const DURATION_TOKEN = "--duration-medium";
+const EASING_TOKEN = "--ease-standard";
+const ACTIVE_SELECTOR = '.os-pill[data-active="true"]';
+
+export type PillNavItem = {
+  href: string;
+  label: string;
+  icon: GlyphName;
+  /** Unread or pending count; hidden at zero. */
+  count?: number;
+};
+
+export type PillNavProps = {
+  items: PillNavItem[];
+  /** The href of the current page; that pill opens to show its label. */
+  activeHref?: string;
+  /** Names the navigation landmark. */
+  label: string;
+  /** `top` sits in a header; `bottom` is a fixed bar for small screens. */
+  placement?: "top" | "bottom";
+};
+
+function boxOf(element: HTMLElement): Box {
+  return { x: element.offsetLeft, width: element.offsetWidth };
+}
+
+/** A click the router will handle in this tab: primary button, no modifier keys. */
+function isPlainClick(event: MouseEvent) {
+  return (
+    !event.defaultPrevented &&
+    event.button === 0 &&
+    !event.metaKey &&
+    !event.ctrlKey &&
+    !event.shiftKey &&
+    !event.altKey
+  );
+}
+
+/**
+ * Keeps one highlight under the active pill. When the active pill changes it glides there,
+ * easing toward the pill's live box each frame, so it tracks the label as it opens and
+ * finishes exactly on the final size. Between changes a ResizeObserver keeps it aligned.
+ */
+function useSlidingIndicator(
+  trackRef: RefObject<HTMLDivElement | null>,
+  indicatorRef: RefObject<HTMLSpanElement | null>,
+  activeKey: string | undefined,
+) {
+  const lastBox = useRef<Box | null>(null);
+  const isAnimating = useRef(false);
+
+  useLayoutEffect(() => {
+    const track = trackRef.current;
+    const indicator = indicatorRef.current;
+    if (!track || !indicator) return;
+    const target = () => track.querySelector<HTMLElement>(ACTIVE_SELECTOR);
+    const place = (box: Box | null) => {
+      lastBox.current = box;
+      indicator.dataset.visible = box ? "true" : "false";
+      if (!box) return;
+      indicator.style.transform = `translateX(${box.x}px)`;
+      indicator.style.width = `${box.width}px`;
+    };
+
+    const to = target();
+    const from = lastBox.current;
+    const styles = getComputedStyle(track);
+    const duration = parseDuration(styles.getPropertyValue(DURATION_TOKEN));
+    const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    if (!to || !from || reduceMotion || duration === 0) {
+      place(to ? boxOf(to) : null);
+      return;
+    }
+
+    const ease = parseEasing(styles.getPropertyValue(EASING_TOKEN));
+    const start = performance.now();
+    let frame = 0;
+    isAnimating.current = true;
+    const step = (now: number) => {
+      const live = target();
+      if (!live) return;
+      const progress = Math.min(1, (now - start) / duration);
+      place(lerpBox(from, boxOf(live), ease(progress)));
+      if (progress < 1) frame = requestAnimationFrame(step);
+      else isAnimating.current = false;
+    };
+    frame = requestAnimationFrame(step);
+    return () => {
+      cancelAnimationFrame(frame);
+      isAnimating.current = false;
+    };
+  }, [activeKey, trackRef, indicatorRef]);
+
+  useLayoutEffect(() => {
+    const track = trackRef.current;
+    const indicator = indicatorRef.current;
+    if (!track || !indicator) return;
+    const observer = new ResizeObserver(() => {
+      if (isAnimating.current) return;
+      const active = track.querySelector<HTMLElement>(ACTIVE_SELECTOR);
+      if (!active) return;
+      const box = boxOf(active);
+      lastBox.current = box;
+      indicator.style.transform = `translateX(${box.x}px)`;
+      indicator.style.width = `${box.width}px`;
+    });
+    observer.observe(track);
+    return () => observer.disconnect();
+  }, [trackRef, indicatorRef]);
+}
+
+/**
+ * App navigation as a row of pills: each page is an icon, and the page you are on opens to
+ * icon + label in the accent colour. A click opens the pill at once, before the next page
+ * arrives, while one highlight slides across and the label opens to its natural width.
+ */
+export function PillNav({ items, activeHref, label, placement = "top" }: PillNavProps) {
+  const LinkComponent = useLinkComponent();
+  const trackRef = useRef<HTMLDivElement>(null);
+  const indicatorRef = useRef<HTMLSpanElement>(null);
+
+  // The pill you clicked opens straight away; the route catches up and clears it.
+  const [pendingHref, setPendingHref] = useState<string>();
+  const [routedHref, setRoutedHref] = useState(activeHref);
+  if (routedHref !== activeHref) {
+    setRoutedHref(activeHref);
+    setPendingHref(undefined);
+  }
+  const currentHref = pendingHref ?? activeHref;
+  useSlidingIndicator(trackRef, indicatorRef, currentHref);
+
+  const nav = (
+    <nav aria-label={label} className="os-pill-nav" data-placement={placement}>
+      <div ref={trackRef} className="os-pill-track">
+        <span ref={indicatorRef} className="os-pill-indicator" aria-hidden />
+        <ul className="os-pill-list">
+          {items.map((item) => {
+            const isActive = item.href === currentHref;
+            const count = item.count && item.count > 0 ? item.count : 0;
+            return (
+              <li key={item.href}>
+                <Tooltip content={item.label} isEnabled={!isActive}>
+                  <LinkComponent
+                    href={item.href}
+                    className="os-pill"
+                    data-active={isActive ? "true" : "false"}
+                    aria-current={isActive ? "page" : undefined}
+                    aria-label={count ? `${item.label}, ${count}` : item.label}
+                    onClick={(event: MouseEvent) => {
+                      if (isPlainClick(event)) setPendingHref(item.href);
+                    }}
+                  >
+                    <span className="os-pill-icon">
+                      <Glyph name={item.icon} />
+                      {count ? (
+                        <span className="os-pill-count" aria-hidden>
+                          {count > MAX_COUNT ? `${MAX_COUNT}+` : count}
+                        </span>
+                      ) : null}
+                    </span>
+                    <span className="os-pill-label" aria-hidden>
+                      <span>{item.label}</span>
+                    </span>
+                  </LinkComponent>
+                </Tooltip>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    </nav>
+  );
+  // A fixed bottom bar would cover the end of the page; the spacer keeps that content reachable.
+  return placement === "bottom" ? (
+    <>
+      <div className="os-pill-nav-spacer" aria-hidden />
+      {nav}
+    </>
+  ) : (
+    nav
+  );
+}

package/src/components/Primitives.tsx

@@ -0,0 +1,30 @@
+/**
+ * Layout, text, and icon primitives from Astryx. Everything Joined renders
+ * sits on these, so apps never import Astryx directly.
+ */
+export { Stack, HStack, VStack, StackItem } from "@astryxdesign/core/Stack";
+export type {
+  StackProps,
+  HStackProps,
+  VStackProps,
+  StackAlignment,
+} from "@astryxdesign/core/Stack";
+
+export { Text, Heading } from "@astryxdesign/core/Text";
+export type {
+  TextProps,
+  TextType,
+  TextColor,
+  TextWeight,
+  HeadingProps,
+  HeadingLevel,
+} from "@astryxdesign/core/Text";
+
+export { Card } from "@astryxdesign/core/Card";
+export type { CardProps, CardVariant } from "@astryxdesign/core/Card";
+
+export { Icon } from "@astryxdesign/core/Icon";
+export type { IconProps, IconName, IconSize, IconColor, IconType } from "@astryxdesign/core/Icon";
+
+export { Tooltip } from "@astryxdesign/core/Tooltip";
+export type { TooltipProps } from "@astryxdesign/core/Tooltip";

package/src/components/Rating.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { useState } from "react";
+
+export const RATING_MAX = 5;
+
+export interface RatingProps {
+  value: number;
+  onChange?: (value: number) => void;
+  max?: number;
+  readOnly?: boolean;
+  size?: "sm" | "md" | "lg";
+  label?: string;
+  /** Hides the numeric score. The marks still expose it to assistive tech. */
+  showValue?: boolean;
+  caption?: string;
+}
+
+/** A star score. The number is always written next to the marks. */
+export function Rating({
+  value,
+  onChange,
+  max = RATING_MAX,
+  readOnly = false,
+  size = "md",
+  label = "Rating",
+  showValue = true,
+  caption,
+}: RatingProps) {
+  const [hover, setHover] = useState<number | null>(null);
+  const shown = hover ?? value;
+  const interactive = Boolean(onChange) && !readOnly;
+
+  return (
+    <div className={`os-rating os-rating-${size}`}>
+      <div
+        className="os-rating-stars"
+        role={interactive ? "radiogroup" : "img"}
+        aria-label={interactive ? label : `${label}, ${value} of ${max}`}
+        onMouseLeave={() => setHover(null)}
+      >
+        {Array.from({ length: max }, (_, index) => {
+          const star = index + 1;
+          const filled = shown >= star;
+          if (!interactive) {
+            return (
+              <span key={star} className={filled ? "os-star os-star-on" : "os-star"} aria-hidden>
+                ★
+              </span>
+            );
+          }
+          return (
+            <button
+              key={star}
+              type="button"
+              role="radio"
+              aria-checked={value === star}
+              aria-label={`${star} of ${max}`}
+              className={filled ? "os-star os-star-on" : "os-star"}
+              onMouseEnter={() => setHover(star)}
+              onFocus={() => setHover(star)}
+              onBlur={() => setHover(null)}
+              onClick={() => onChange?.(star)}
+            >
+              ★
+            </button>
+          );
+        })}
+      </div>
+      {showValue && (
+        <span className="os-rating-value">
+          {value} / {max}
+        </span>
+      )}
+      {caption && <span className="os-rating-caption">{caption}</span>}
+    </div>
+  );
+}