@structuralists/scaffolding 0.0.1

package/src/components/Primitives/LinedStack/types.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+
+type Common = {
+  children: ReactNode;
+};
+
+type Plain = {
+  to?: never;
+  href?: never;
+  isExternal?: never;
+  onClick?: never;
+};
+
+type AsRouterLink = {
+  /** In-app navigation. Renders as a React Router `<Link to={to}>`. */
+  to: string;
+  href?: never;
+  isExternal?: never;
+  onClick?: never;
+};
+
+type AsAnchor = {
+  /** External / out-of-app navigation. Renders as a plain `<a href={href}>`. */
+  href: string;
+  /** With `href`, opens in a new tab via `target="_blank" rel="noopener noreferrer"`. */
+  isExternal?: boolean;
+  to?: never;
+  onClick?: never;
+};
+
+type AsButton = {
+  to?: never;
+  href?: never;
+  isExternal?: never;
+  /** Renders as a `<button>`. */
+  onClick: () => void;
+};
+
+/**
+ * Provide at most one of `to` (router link), `href` (plain `<a>`), or
+ * `onClick` (button). With none, renders a plain non-interactive `<div>`.
+ *
+ * Implemented as a discriminated union so TypeScript rejects combinations
+ * — but the resulting error can be confusing (it surfaces as a multi-variant
+ * mismatch rather than a single targeted message). If you see a strange
+ * type error on `LinedStack`, the first thing to check is whether you've
+ * passed more than one of `to` / `href` / `onClick`.
+ */
+export type LinedStackProps = Common & (Plain | AsRouterLink | AsAnchor | AsButton);

package/src/components/Primitives/LongText/LongText.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { LongText } from './index';
+
+const meta: Meta<typeof LongText> = {
+  title: 'Primitives/LongText',
+  component: LongText,
+};
+
+export default meta;
+type Story = StoryObj<typeof LongText>;
+
+const SHORT = 'A short string.';
+const LONG =
+  'This is a much longer string that will exceed the width of its container, ' +
+  'forcing LongText to render with an ellipsis. Click (or focus + Enter) to ' +
+  'open a popover with the full content. The popover wraps and is selectable.';
+
+const Cell = ({ children }: { children: React.ReactNode }) => (
+  <div
+    style={{
+      width: 220,
+      border: '1px solid var(--ui-border-subtle)',
+      padding: 8,
+      borderRadius: 'var(--ui-radius)',
+      background: 'var(--ui-background-0)',
+    }}
+  >
+    {children}
+  </div>
+);
+
+export const InsideFixedWidth: Story = {
+  name: 'Inside a fixed-width container',
+  render: () => (
+    <div style={{ padding: 24, display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <Cell>
+        <LongText>{SHORT}</LongText>
+      </Cell>
+      <Cell>
+        <LongText>{LONG}</LongText>
+      </Cell>
+      <Cell>
+        <LongText>{null}</LongText>
+      </Cell>
+    </div>
+  ),
+};
+
+export const ResizesLive: Story = {
+  name: 'Resize handle — interactivity tracks overflow state',
+  render: () => (
+    <div style={{ padding: 24 }}>
+      <p style={{ color: 'var(--ui-muted)', fontSize: 'var(--ui-text-small)' }}>
+        Drag the bottom-right corner to resize. The component becomes interactive only when the
+        text overflows.
+      </p>
+      <div
+        style={{
+          width: 320,
+          resize: 'horizontal',
+          overflow: 'auto',
+          border: '1px dashed var(--ui-border)',
+          padding: 8,
+          borderRadius: 'var(--ui-radius)',
+          background: 'var(--ui-background-0)',
+        }}
+      >
+        <LongText>{LONG}</LongText>
+      </div>
+    </div>
+  ),
+};

package/src/components/Primitives/LongText/index.tsx

@@ -0,0 +1,67 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+import type { KeyboardEvent } from 'react';
+import { Popover } from '../../Overlays/Popover';
+import { EmptyValue } from '../EmptyValue';
+import { cx } from '../../../utils';
+import type { LongTextProps } from './types';
+import styles from './styles.module.css';
+
+export const LongText = (props: LongTextProps) => {
+  const { children } = props;
+
+  const triggerRef = useRef<HTMLSpanElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [isOverflowing, setIsOverflowing] = useState(false);
+
+  useLayoutEffect(() => {
+    const el = triggerRef.current;
+    if (!el) return;
+    const check = () => setIsOverflowing(el.scrollWidth > el.clientWidth + 1);
+    check();
+    const ro = new ResizeObserver(check);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [children]);
+
+  if (children == null || children === '') return <EmptyValue />;
+
+  const onKeyDown = (e: KeyboardEvent<HTMLSpanElement>) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      setIsOpen(true);
+    }
+  };
+
+  const interactive = isOverflowing
+    ? {
+        role: 'button' as const,
+        tabIndex: 0,
+        onClick: () => setIsOpen(true),
+        onKeyDown,
+      }
+    : {};
+
+  return (
+    <>
+      <span
+        ref={triggerRef}
+        className={cx(styles.text, isOverflowing && styles.interactive)}
+        {...interactive}
+      >
+        {children}
+      </span>
+      {isOpen ? (
+        <Popover
+          anchorRef={triggerRef}
+          isOpen={isOpen}
+          onClose={() => setIsOpen(false)}
+          ariaLabel="Full text"
+        >
+          <div className={styles.fullText}>{children}</div>
+        </Popover>
+      ) : null}
+    </>
+  );
+};
+
+export type { LongTextProps };

package/src/components/Primitives/LongText/styles.module.css

@@ -0,0 +1,30 @@
+.text {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 100%;
+  border-radius: var(--ui-radius);
+}
+
+.interactive {
+  cursor: pointer;
+}
+
+.interactive:hover {
+  background-color: var(--ui-background-1);
+}
+
+.interactive:focus-visible {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: 1px;
+}
+
+.fullText {
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-width: 480px;
+  font-size: var(--ui-text-small);
+  line-height: var(--ui-line-height);
+  color: var(--ui-foreground);
+}

package/src/components/Primitives/LongText/types.ts

@@ -0,0 +1,4 @@
+export type LongTextProps = {
+  /** The full text. Renders truncated; opens a popover with the full content when truncated. */
+  children: string | null | undefined;
+};

package/src/components/Primitives/Num/Num.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Num } from './index';
+
+const meta: Meta<typeof Num> = {
+  title: 'Primitives/Num',
+  component: Num,
+};
+
+export default meta;
+type Story = StoryObj<typeof Num>;
+
+const Row = ({ label, children }: { label: string; children: React.ReactNode }) => (
+  <div style={{ display: 'flex', gap: 16, padding: '4px 0' }}>
+    <span style={{ width: 220, color: 'var(--ui-muted)' }}>{label}</span>
+    <span>{children}</span>
+  </div>
+);
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <Row label="decimal (default)">
+        <Num value={1234567.89} />
+      </Row>
+      <Row label="integer">
+        <Num value={1234567.89} as="integer" />
+      </Row>
+      <Row label="currency (USD default)">
+        <Num value={1234.5} as="currency" />
+      </Row>
+      <Row label="currency EUR">
+        <Num value={1234.5} as="currency" currency="EUR" />
+      </Row>
+      <Row label="compact (1234)">
+        <Num value={1234} as="compact" />
+      </Row>
+      <Row label="compact (3_400_000)">
+        <Num value={3_400_000} as="compact" />
+      </Row>
+      <Row label="null value">
+        <Num value={null} />
+      </Row>
+      <Row label="undefined value">
+        <Num value={undefined} />
+      </Row>
+      <Row label="NaN">
+        <Num value={NaN} />
+      </Row>
+    </div>
+  ),
+};

package/src/components/Primitives/Num/index.tsx

@@ -0,0 +1,37 @@
+import { EmptyValue } from '../EmptyValue';
+import type { NumProps, NumVariant } from './types';
+
+const optionsFor = (
+  variant: NumVariant,
+  precision: number | undefined,
+  currency: string,
+): Intl.NumberFormatOptions => {
+  if (variant === 'integer') {
+    return { maximumFractionDigits: 0 };
+  }
+  if (variant === 'currency') {
+    return precision != null
+      ? {
+          style: 'currency',
+          currency,
+          minimumFractionDigits: precision,
+          maximumFractionDigits: precision,
+        }
+      : { style: 'currency', currency };
+  }
+  if (variant === 'compact') {
+    return { notation: 'compact', maximumFractionDigits: precision ?? 1 };
+  }
+  return precision != null
+    ? { minimumFractionDigits: precision, maximumFractionDigits: precision }
+    : {};
+};
+
+export const Num = (props: NumProps) => {
+  const { value, as = 'decimal', precision, currency = 'USD' } = props;
+
+  if (value == null || Number.isNaN(value)) return <EmptyValue />;
+  return <>{value.toLocaleString(undefined, optionsFor(as, precision, currency))}</>;
+};
+
+export type { NumProps, NumVariant };

package/src/components/Primitives/Num/types.ts

@@ -0,0 +1,19 @@
+export type NumVariant = 'decimal' | 'integer' | 'currency' | 'compact';
+
+export type NumProps = {
+  value: number | null | undefined;
+  /**
+   * Format variant. Defaults to `decimal` (locale-aware separators).
+   * - `integer`: rounded to whole, with separators
+   * - `currency`: locale currency, defaults to USD
+   * - `compact`: 1.2K / 3.4M / 5.6B
+   *
+   * For percent, use the `Percent` component — its `fractionalValue` prop
+   * makes the 0.42-vs-42 input convention obvious at the call site.
+   */
+  as?: NumVariant;
+  /** Override fraction digits. Variant-specific defaults apply when omitted. */
+  precision?: number;
+  /** ISO currency code for `as='currency'`. Defaults to 'USD'. */
+  currency?: string;
+};

package/src/components/Primitives/Percent/Percent.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Percent } from './index';
+
+const meta: Meta<typeof Percent> = {
+  title: 'Primitives/Percent',
+  component: Percent,
+};
+
+export default meta;
+type Story = StoryObj<typeof Percent>;
+
+const Row = ({ label, children }: { label: string; children: React.ReactNode }) => (
+  <div style={{ display: 'flex', gap: 16, padding: '4px 0' }}>
+    <span style={{ width: 220, color: 'var(--ui-muted)' }}>{label}</span>
+    <span>{children}</span>
+  </div>
+);
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <Row label="0.42">
+        <Percent fractionalValue={0.42} />
+      </Row>
+      <Row label="0.4256, precision=1">
+        <Percent fractionalValue={0.4256} precision={1} />
+      </Row>
+      <Row label="0.4256, precision=2">
+        <Percent fractionalValue={0.4256} precision={2} />
+      </Row>
+      <Row label="1 (full)">
+        <Percent fractionalValue={1} />
+      </Row>
+      <Row label="0 (none)">
+        <Percent fractionalValue={0} />
+      </Row>
+      <Row label="negative (-0.05)">
+        <Percent fractionalValue={-0.05} />
+      </Row>
+      <Row label="null">
+        <Percent fractionalValue={null} />
+      </Row>
+      <Row label="NaN">
+        <Percent fractionalValue={NaN} />
+      </Row>
+    </div>
+  ),
+};

package/src/components/Primitives/Percent/index.tsx

@@ -0,0 +1,15 @@
+import { EmptyValue } from '../EmptyValue';
+import type { PercentProps } from './types';
+
+export const Percent = (props: PercentProps) => {
+  const { fractionalValue, precision } = props;
+
+  if (fractionalValue == null || Number.isNaN(fractionalValue)) return <EmptyValue />;
+  const options: Intl.NumberFormatOptions =
+    precision != null
+      ? { style: 'percent', maximumFractionDigits: precision, minimumFractionDigits: precision }
+      : { style: 'percent' };
+  return <>{fractionalValue.toLocaleString(undefined, options)}</>;
+};
+
+export type { PercentProps };

package/src/components/Primitives/Percent/types.ts

@@ -0,0 +1,10 @@
+export type PercentProps = {
+  /**
+   * Fractional input — `0.42` renders as `42%`. Named `fractionalValue` (not
+   * just `value`) so the convention is obvious at the call site without
+   * needing to read the source.
+   */
+  fractionalValue: number | null | undefined;
+  /** Override fraction digits. When omitted, no fixed precision is set. */
+  precision?: number;
+};

package/src/components/Primitives/RelativeTime/RelativeTime.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { RelativeTime } from './index';
+
+const meta: Meta<typeof RelativeTime> = {
+  title: 'Primitives/RelativeTime',
+  component: RelativeTime,
+};
+
+export default meta;
+type Story = StoryObj<typeof RelativeTime>;
+
+const Row = ({ label, children }: { label: string; children: React.ReactNode }) => (
+  <div style={{ display: 'flex', gap: 16, padding: '4px 0' }}>
+    <span style={{ width: 220, color: 'var(--ui-muted)' }}>{label}</span>
+    <span>{children}</span>
+  </div>
+);
+
+const ago = (ms: number) => new Date(Date.now() - ms);
+const ahead = (ms: number) => new Date(Date.now() + ms);
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <Row label="seconds ago">
+        <RelativeTime value={ago(15_000)} />
+      </Row>
+      <Row label="minutes ago">
+        <RelativeTime value={ago(5 * 60_000)} />
+      </Row>
+      <Row label="hours ago">
+        <RelativeTime value={ago(3 * 3_600_000)} />
+      </Row>
+      <Row label="days ago">
+        <RelativeTime value={ago(4 * 86_400_000)} />
+      </Row>
+      <Row label="future (5 min)">
+        <RelativeTime value={ahead(5 * 60_000)} />
+      </Row>
+      <Row label="far past (45 days)">
+        <RelativeTime value={ago(45 * 86_400_000)} />
+      </Row>
+      <Row label="ISO string">
+        <RelativeTime value={ago(2 * 3_600_000).toISOString()} />
+      </Row>
+      <Row label="numeric epoch ms">
+        <RelativeTime value={Date.now() - 60_000} />
+      </Row>
+      <Row label="null">
+        <RelativeTime value={null} />
+      </Row>
+      <Row label="invalid string">
+        <RelativeTime value="not a date" />
+      </Row>
+    </div>
+  ),
+};

package/src/components/Primitives/RelativeTime/index.tsx

@@ -0,0 +1,31 @@
+import { EmptyValue } from '../EmptyValue';
+import type { RelativeTimeProps } from './types';
+
+const toDate = (v: Date | string | number): Date => (v instanceof Date ? v : new Date(v));
+
+const formatRelative = (date: Date): string => {
+  const diffMs = Date.now() - date.getTime();
+  const past = diffMs >= 0;
+  const abs = Math.abs(diffMs);
+  const seconds = Math.round(abs / 1000);
+  const minutes = Math.round(seconds / 60);
+  const hours = Math.round(minutes / 60);
+  const days = Math.round(hours / 24);
+  const suffix = past ? 'ago' : 'from now';
+  if (seconds < 60) return `${seconds}s ${suffix}`;
+  if (minutes < 60) return `${minutes}m ${suffix}`;
+  if (hours < 24) return `${hours}h ${suffix}`;
+  if (days < 30) return `${days}d ${suffix}`;
+  return date.toLocaleDateString();
+};
+
+export const RelativeTime = (props: RelativeTimeProps) => {
+  const { value } = props;
+
+  if (value == null) return <EmptyValue />;
+  const d = toDate(value);
+  if (Number.isNaN(d.getTime())) return <EmptyValue />;
+  return <>{formatRelative(d)}</>;
+};
+
+export type { RelativeTimeProps };

package/src/components/Primitives/RelativeTime/types.ts

@@ -0,0 +1,3 @@
+export type RelativeTimeProps = {
+  value: Date | string | number | null | undefined;
+};