@iamfiro/design 0.0.0-stage → 0.3.0

package/lib/types/primitives/StatusIcon.d.ts

@@ -0,0 +1,40 @@
+import type { CSSProperties } from 'react';
+import './Spinner.css';
+import './StatusIcon.css';
+export type StatusIconStatus = 'pending' | 'active' | 'done' | 'error' | 'warning';
+export type StatusIconSize = 'sm' | 'md' | 'lg';
+export interface StatusIconProps {
+    status: StatusIconStatus;
+    /** A named size or a pixel number. */
+    size?: StatusIconSize | number;
+    /**
+     * With `active`: 0–100 fills the blue ring to that point. Leave undefined for an
+     * indeterminate ring that spins (same arc as Spinner).
+     */
+    progress?: number;
+    /** `done` in green instead of the default quiet gray. */
+    colored?: boolean;
+    /**
+     * A step number ("5") in a solid gray outline instead of the dashed pending circle. With the
+     * other statuses the icon still turns into its ring or glyph, unless `persistNumber`.
+     */
+    number?: number | string;
+    /**
+     * With `number`: keep the number in every status. The outline takes the status colour instead
+     * (gray done, blue active, red error, orange warning) — for numbered timelines.
+     */
+    persistNumber?: boolean;
+    /** Read by screen readers. Defaults to the status in Korean ("완료", "진행 중 40%"). */
+    label?: string;
+    /** Hide from screen readers when the row text already says the status. */
+    decorative?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The small circle at the start of a checklist / schedule row: dashed gray (pending), blue ring
+ * (active), gray check (done), red × (error), orange ! (warning). All states live in one svg, so a
+ * status change crossfades — the ring fills, the check draws itself in — instead of swapping icons.
+ * With `number`, pending shows a numbered outline ("5") instead of the dashed circle.
+ */
+export declare function StatusIcon({ status, size, progress, colored, number, persistNumber, label, decorative, className, style, }: StatusIconProps): import("react").JSX.Element;

package/lib/types/primitives/Swatch.d.ts

@@ -0,0 +1,11 @@
+import './Swatch.css';
+export interface SwatchProps {
+    /** A CSS custom property name (`--accent`) or any CSS color. */
+    color: string;
+    /** Defaults to the token name. */
+    name?: string;
+    /** Print the resolved hex/rgb value under the name. */
+    showValue?: boolean;
+}
+/** A color chip for token docs: the color, its token name and resolved value. */
+export declare function Swatch({ color, name, showValue }: SwatchProps): import("react").JSX.Element;

package/lib/types/primitives/Tooltip.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import './Tooltip.css';
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipProps {
+    /** Text (or small inline content) shown in the bubble. */
+    content: ReactNode;
+    /** Which side of the trigger the bubble opens on. */
+    side?: TooltipSide;
+    /** Hover delay before the first tooltip opens; neighbours opened right after skip it. */
+    delay?: number;
+    children: ReactNode;
+}
+/**
+ * Hover waits `delay` so sweeping across a toolbar doesn't flash bubbles; once one is open,
+ * neighbours open instantly. Keyboard focus opens at once; a press or Esc closes it.
+ */
+export declare function Tooltip({ content, side, delay, children }: TooltipProps): import("react").JSX.Element;

package/lib/types/primitives/Typography.d.ts

@@ -0,0 +1,48 @@
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, ElementType, ReactNode } from 'react';
+import './Typography.css';
+export type TextVariant = 'display-lg' | 'display-md' | 'display-sm' | 'heading-xl' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'heading-xs' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs' | 'label-lg' | 'label-md' | 'label-sm' | 'label-xs' | 'caption' | 'overline' | 'number-xl' | 'number-lg' | 'number-md' | 'number-sm' | 'code';
+export type TextTone = 'default' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'warning' | 'danger' | 'inverse' | 'inherit';
+export type TextWeight = 'regular' | 'medium' | 'semibold' | 'bold';
+interface TextOwnProps<E extends ElementType> {
+    /** Element to render; defaults by role (heading → h2, body → p, label → span, code → code). */
+    as?: E;
+    variant?: TextVariant;
+    tone?: TextTone;
+    /** Overrides the role's weight. */
+    weight?: TextWeight;
+    align?: 'start' | 'center' | 'end';
+    /** One line with an ellipsis. */
+    truncate?: boolean;
+    /** Clamp to N lines with an ellipsis. */
+    lineClamp?: number;
+    /** Tabular, lining figures so numbers line up in columns and don't jitter while counting. */
+    numeric?: boolean;
+    /** Balanced line lengths (headings) or no lonely last word (paragraphs). */
+    wrap?: 'balance' | 'pretty';
+    /** A line drawn through the text (done to-dos). Animates when toggled; works on inline text (use as="span"). */
+    strike?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+export type TextProps<E extends ElementType = 'span'> = TextOwnProps<E> & Omit<ComponentPropsWithRef<E>, keyof TextOwnProps<E>>;
+/** Any text, set in one of the type roles from tokens.css. */
+export declare function Text<E extends ElementType = 'span'>({ as, variant, tone, weight, align, truncate, lineClamp, numeric, wrap, strike, className, style, children, ...rest }: TextProps<E>): import("react").JSX.Element;
+export type HeadingProps = Omit<TextProps<'h2'>, 'as' | 'variant'> & {
+    /** Document outline level (h1–h6). */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Visual size, independent of the level (e.g. an h2 that looks like display-sm). */
+    size?: TextVariant;
+};
+/** A heading whose look follows its level unless `size` says otherwise. */
+export declare function Heading({ level, size, wrap, ...rest }: HeadingProps): import("react").JSX.Element;
+export interface ProseProps extends ComponentPropsWithoutRef<'div'> {
+    /** Text size of the whole block; headings and spacing scale with it. */
+    size?: 'sm' | 'md' | 'lg';
+}
+/**
+ * Styles plain HTML (h1–h4, p, lists, blockquote, code, pre, table, hr, a) for
+ * docs, changelogs, help articles and AI answers — e.g. rendered Markdown.
+ */
+export declare function Prose({ size, className, ...rest }: ProseProps): import("react").JSX.Element;
+export {};

package/lib/types/primitives/formatCountdown.d.ts

@@ -0,0 +1,2 @@
+/** "8초" under a minute, "1:05" under an hour, "1:02:05" beyond. */
+export declare function formatCountdown(seconds: number): string;

package/lib/types/primitives/formatElapsed.d.ts

@@ -0,0 +1,8 @@
+export type ElapsedFormatStyle = 'clock' | 'text' | 'short';
+/**
+ * Time that has passed, in seconds, as text.
+ * - clock (default): "0:08", "17:40", "1:02:05"
+ * - text: "8초", "17분 40초", "1시간 2분"
+ * - short: "8s", "17m 40s", "1h 2m" — for tight trailing columns
+ */
+export declare function formatElapsed(seconds: number, style?: ElapsedFormatStyle): string;

package/lib/types/primitives/formatRelativeTime.d.ts

@@ -0,0 +1,16 @@
+/** Anything `new Date()` understands. */
+export type DateInput = Date | string | number;
+export declare const toDate: (input: DateInput) => Date;
+/**
+ * Korean relative time: "방금", "3분 전", "2시간 전", "어제", "4일 전", "10월 25일", "2025년 3월 2일".
+ * Future dates read "5분 후", "내일", "3일 후".
+ */
+export declare function formatRelativeTime(input: DateInput, now?: Date): string;
+/** The full date for tooltips: "2026년 10월 25일 오후 3:24". */
+export declare function formatFullDate(input: DateInput): string;
+/**
+ * How long until `formatRelativeTime` would print something different, so a live label can
+ * wake up exactly then instead of polling: every minute for the first hour, then every hour,
+ * then at midnight (capped at an hour).
+ */
+export declare function nextRelativeTimeChange(input: DateInput, now?: Date): number;

package/lib/types/primitives/hotkey.d.ts

@@ -0,0 +1,10 @@
+/** Inputs, textareas, selects and contenteditable — places where a plain letter is typing, not a command. */
+export declare function isTypingTarget(target: EventTarget | null): boolean;
+/**
+ * Does this keydown match a shortcut written as Kbd key names (`['A']`, `['mod', 'enter']`)?
+ * Letters and digits also match by physical key (`e.code`), so a shortcut still works while a
+ * Korean keyboard layout is on (ㅁ is the A key). Modifiers must match exactly.
+ */
+export declare function matchesHotkey(e: KeyboardEvent, keys: string[]): boolean;
+/** Kbd key names → the `aria-keyshortcuts` form ("Control+Enter", "A"). */
+export declare function toAriaShortcut(keys: string[]): string;

package/lib/types/primitives/index.d.ts

@@ -0,0 +1,188 @@
+import { type ButtonHTMLAttributes, type CSSProperties, type HTMLAttributes, type InputHTMLAttributes, type ReactNode, type Ref, type SelectHTMLAttributes, type TextareaHTMLAttributes } from 'react';
+import './primitives.css';
+/** Joins truthy class names. */
+export declare const cx: (...c: Array<string | false | null | undefined>) => string;
+type Size = 'sm' | 'md' | 'lg';
+export type ButtonVariant = 'primary' | 'accent' | 'secondary' | 'outline' | 'ghost' | 'danger';
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: Size;
+    icon?: ReactNode;
+    iconRight?: ReactNode;
+    /** Square button that only shows `icon`. Pass `aria-label`. */
+    iconOnly?: boolean;
+    loading?: boolean;
+    block?: boolean;
+    /**
+     * A keyboard hint after the label, as Kbd key names: `"A"`, `['mod', 'enter']`.
+     * Only shows the hint; add `hotkey` to also listen for it.
+     */
+    shortcut?: string | string[];
+    /**
+     * Pressing `shortcut` anywhere on the page clicks the button. Plain keys are ignored while
+     * typing in a field and during IME composition (combos with ⌘/Ctrl/Alt still work); a disabled,
+     * loading or inert button ignores it.
+     */
+    hotkey?: boolean;
+}
+export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare function Field({ label, hint, invalid, children, htmlFor, }: {
+    label?: ReactNode;
+    hint?: ReactNode;
+    invalid?: boolean;
+    children: ReactNode;
+    htmlFor?: string;
+}): import("react").JSX.Element;
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    size?: Size;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    invalid?: boolean;
+    /**
+     * No border, fill, focus ring, radius or side padding in any state — for an input that sits
+     * inside another surface which draws all of that (command palette search row). Height and
+     * font still follow `size`; the parent sets the outer padding.
+     */
+    bare?: boolean;
+    wrapperClassName?: string;
+    wrapperStyle?: CSSProperties;
+    /** The outer field (.ds-input), e.g. to anchor a popover to the whole field. `ref` is the <input>. */
+    wrapperRef?: Ref<HTMLDivElement>;
+}
+export declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<HTMLInputElement>>;
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Grow with the content instead of scrolling, up to `maxRows`. */
+    autoResize?: boolean;
+    /** With `autoResize`: the height stops here and the rest scrolls. */
+    maxRows?: number;
+    /** No border, fill or padding — for a textarea that sits inside another surface (ChatComposer). */
+    bare?: boolean;
+}
+export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaProps & import("react").RefAttributes<HTMLTextAreaElement>>;
+export declare function NativeSelect({ children, style, ...rest }: SelectHTMLAttributes<HTMLSelectElement>): import("react").JSX.Element;
+type ToggleProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> & {
+    label?: ReactNode;
+};
+export type CheckboxProps = ToggleProps & {
+    /** square (default) or circle — circles fill blue, for checklists and to-dos. */
+    shape?: 'square' | 'circle';
+};
+export declare function Checkbox({ label, shape, className, ...rest }: CheckboxProps): import("react").JSX.Element;
+export declare function Radio({ label, className, ...rest }: ToggleProps): import("react").JSX.Element;
+export declare function Switch({ label, className, ...rest }: ToggleProps): import("react").JSX.Element;
+export type Tone = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+export type BadgeSize = 'sm' | 'md';
+export interface BadgeProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
+    tone?: Tone;
+    /** Small status dot before the text. */
+    dot?: boolean;
+    /** The dot pulses — something live or happening right now. Implies `dot`. */
+    pulse?: boolean;
+    /** A small spinner before the text — something still running. Takes the place of `dot` and `icon`. */
+    spinner?: boolean;
+    /** Less rounded corners (versions, codes). */
+    square?: boolean;
+    /** Icon before the text. */
+    icon?: ReactNode;
+    /** Icon after the text. */
+    iconRight?: ReactNode;
+    /** Trailing chevron: the badge opens or leads somewhere. Usually with `as="button"`. */
+    chevron?: boolean;
+    /** sm: 18px high, for dense rows and next to headings. */
+    size?: BadgeSize;
+    /** A tiny uppercase tag in the overline type role ("BEST", "NEW"). */
+    overline?: boolean;
+    /** 'button' makes the badge clickable: hover fill, focus ring, press. */
+    as?: 'span' | 'button';
+    /** With `as="button"`. */
+    disabled?: boolean;
+}
+export declare function Badge({ tone, dot, pulse, spinner, square, icon, iconRight, chevron, size, overline, as, disabled, className, children, ...rest }: BadgeProps): import("react").JSX.Element;
+export declare function Avatar({ name, size, square, online, color, tooltip, }: {
+    name: string;
+    size?: number;
+    square?: boolean;
+    online?: boolean;
+    color?: string;
+    /** Hover shows the full name in a Tooltip; pass content to show something else, `false` to turn it off. */
+    tooltip?: boolean | ReactNode;
+}): import("react").JSX.Element;
+/** Overlapping avatars with a "+N" overflow — an IconStack of Avatars. */
+export declare function AvatarGroup({ names, size, max }: {
+    names: string[];
+    size?: number;
+    max?: number;
+}): import("react").JSX.Element;
+export interface SegmentOption<T extends string> {
+    value: T;
+    label: ReactNode;
+    icon?: ReactNode;
+    count?: number;
+}
+export type SegmentedVariant = 'pill' | 'underline' | 'chip' | 'text';
+export declare function SegmentedControl<T extends string>({ options, value, onChange, variant, ariaLabel, }: {
+    options: SegmentOption<T>[];
+    value: T;
+    onChange: (v: T) => void;
+    /** pill: sunken track · underline: tab bar · chip: separate bordered items · text: borderless, text only */
+    variant?: SegmentedVariant;
+    ariaLabel?: string;
+}): import("react").JSX.Element;
+export { Kbd, formatKey, isMac } from './Kbd';
+export type { KbdProps } from './Kbd';
+export { Flag } from './Flag';
+export type { FlagCode, FlagProps } from './Flag';
+export { Tooltip } from './Tooltip';
+export type { TooltipProps, TooltipSide } from './Tooltip';
+export { SearchInput } from './SearchInput';
+export type { SearchInputProps } from './SearchInput';
+export { Heading, Prose, Text } from './Typography';
+export type { HeadingProps, ProseProps, TextProps, TextTone, TextVariant, TextWeight } from './Typography';
+export { Spinner } from './Spinner';
+export type { SpinnerProps, SpinnerSize, SpinnerTone } from './Spinner';
+export { Progress, ProgressCircle } from './Progress';
+export type { ProgressCircleProps, ProgressProps, ProgressSegment, ProgressTone } from './Progress';
+export { FileIcon, fileKind } from './FileIcon';
+export type { FileIconProps, FileKind } from './FileIcon';
+export { CopyButton } from './CopyButton';
+export type { CopyButtonProps } from './CopyButton';
+export { Swatch } from './Swatch';
+export type { SwatchProps } from './Swatch';
+export { BrandIcon, BRAND_NAMES } from './BrandIcon';
+export type { BrandIconProps, BrandName } from './BrandIcon';
+export { ColorDot } from './ColorDot';
+export type { ColorDotProps, ColorDotVariant } from './ColorDot';
+export { Box, Grid, Inline, Separator, Stack } from './Layout';
+export type { BoxProps, GridProps, InlineProps, SeparatorProps, Space, StackProps } from './Layout';
+export { AspectRatio } from './AspectRatio';
+export type { AspectRatioProps } from './AspectRatio';
+export { RelativeTime } from './RelativeTime';
+export type { RelativeTimeProps } from './RelativeTime';
+export { formatFullDate, formatRelativeTime, nextRelativeTimeChange } from './formatRelativeTime';
+export type { DateInput } from './formatRelativeTime';
+export { IconTile } from './IconTile';
+export type { IconTileProps, IconTileTone } from './IconTile';
+export { SelectorButton } from './SelectorButton';
+export type { SelectorButtonProps, SelectorButtonSize } from './SelectorButton';
+export { StatusIcon } from './StatusIcon';
+export type { StatusIconProps, StatusIconSize, StatusIconStatus } from './StatusIcon';
+export { Delta } from './Delta';
+export type { DeltaDirection, DeltaProps, DeltaVariant } from './Delta';
+export { IconStack } from './IconStack';
+export type { IconStackProps } from './IconStack';
+export { Countdown } from './Countdown';
+export type { CountdownProps } from './Countdown';
+export { formatCountdown } from './formatCountdown';
+export { Elapsed } from './Elapsed';
+export type { ElapsedProps } from './Elapsed';
+export { formatElapsed } from './formatElapsed';
+export type { ElapsedFormatStyle } from './formatElapsed';
+export { CountBadge } from './CountBadge';
+export type { CountBadgeProps, CountBadgeSize, CountBadgeVariant } from './CountBadge';
+export { matchesHotkey, isTypingTarget, toAriaShortcut } from './hotkey';
+export { Link } from './Link';
+export type { LinkProps, LinkVariant } from './Link';
+export { MaskedText } from './MaskedText';
+export type { MaskedTextProps } from './MaskedText';
+export { maskParts, maskValue } from './maskValue';
+export type { MaskedParts, MaskOptions } from './maskValue';

package/lib/types/primitives/maskValue.d.ts

@@ -0,0 +1,24 @@
+export interface MaskOptions {
+    /** Characters kept at the start. */
+    visibleStart?: number;
+    /** Characters kept at the end. */
+    visibleEnd?: number;
+    /** The hiding character. */
+    mask?: string;
+    /** Bullets per group; groups are separated by a space. */
+    groupSize?: number;
+    /** How many bullets to draw. Default: one group, so the real length isn't given away. */
+    maskLength?: number;
+}
+export interface MaskedParts {
+    start: string;
+    hidden: string;
+    end: string;
+}
+/**
+ * Splits a secret into what stays visible and the bullets between ("DE89 •••• 3000").
+ * Whitespace in the value is ignored. Values too short to keep both ends are fully hidden.
+ */
+export declare function maskParts(value: string, { visibleStart, visibleEnd, mask, groupSize, maskLength }?: MaskOptions): MaskedParts;
+/** The masked string in one piece: `maskValue('DE89370400440532013000')` → "DE89 •••• 3000". */
+export declare function maskValue(value: string, options?: MaskOptions): string;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@iamfiro/design",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Lumen 디자인 시스템 — React 컴포넌트 · 토큰 · 훅. 에이전트는 AGENTS.md부터 읽는다.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./style.css": "./lib/style.css",
+    "./AGENTS.md": "./AGENTS.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "agents",
+    "AGENTS.md"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "oxlint",
+    "preview": "vite preview",
+    "build:lib": "node -e \"fs.rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.lib.json && vite build -c vite.lib.config.ts",
+    "gen:agents": "node scripts/gen-agents.ts",
+    "prepublishOnly": "npm run gen:agents && npm run build:lib"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "lucide-react": "^1.61.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "javascript-obfuscator": "^5.9.0",
+    "oxlint": "^1.88.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.4"
+  }
+}