@musecat/uikit 0.1.1 → 0.1.2

package/.agents/references/Components/Radio.md

@@ -0,0 +1,68 @@
+# Radio
+
+## Purpose
+
+The `Radio` component provides a radio button UI that lets the user select a single option among multiple choices. It supports custom theming, controlled/uncontrolled state management, and labels.
+
+## Usage Logic
+
+- **Controlled/Uncontrolled**: Depending on the presence of the `checked` prop, it acts as a controlled or uncontrolled component.
+- **Grouped State**: `Radio` components with the same `name` synchronize their state via the native `change` event.
+- **Styling**: Combined with the theme system (`ThemeSystemProps`), allowing various presets, background, color, and size (`UIKitSizeValue`) adjustments. Providing a `title` renders a text label together, and `titleSpaceBetween` or `reversed` adjusts the layout.
+
+## Type Signatures
+
+```typescript
+import type { RadiusProps } from "@/packages/Frameworks/Theme/Radius.types";
+import type { UIKitSizeValue } from "../../Frameworks/_shared/sizing";
+import type {
+  BorderProps,
+  ThemeSystemProps,
+} from "../../Frameworks/Theme/Theme.types";
+import type { TextProps } from "../Text/Text.types";
+
+export interface RadioProps
+  extends
+    Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "color">,
+    BorderProps,
+    RadiusProps,
+    ThemeSystemProps {
+  title?: string;
+  titleType?: TextProps["type"];
+  titleSpaceBetween?: boolean;
+  reversed?: boolean;
+  readOnly?: boolean;
+  size?: UIKitSizeValue;
+}
+```
+
+## Example Code
+
+```tsx
+import Radio from "@/packages/Components/Radio/Radio";
+import { useState } from "react";
+
+export default function RadioExample() {
+  const [selected, setSelected] = useState("apple");
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "10px" }}>
+      <Radio
+        name="fruit"
+        value="apple"
+        title="Apple"
+        checked={selected === "apple"}
+        onChange={(e) => setSelected(e.target.value)}
+      />
+      <Radio
+        name="fruit"
+        value="banana"
+        title="Banana"
+        checked={selected === "banana"}
+        onChange={(e) => setSelected(e.target.value)}
+      />
+      <Radio name="fruit" value="cherry" title="Cherry" disabled />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Select.md

@@ -0,0 +1,80 @@
+# Select
+
+## Purpose
+
+The `Select` component provides a dropdown menu for receiving single or multiple item selection from the user. It natively supports accessibility and keyboard navigation, and is provided as a custom UI wrapping the native `<select>` element.
+
+## Usage Logic
+
+- **Single/Multiple Selection**: The type signature and return value differ based on the `multiple` prop value (`string` or `string[]`). Generics are used so the value type received in `onChange` is automatically inferred.
+- **Option structure**: Uses `Option` (value, label, description, icon) objects or `OptGroup` object arrays rather than a simple string array. Internally composed of `Select.trigger.tsx` (control Pressable), `select.control.tsx` (control + combobox orchestration), and `select.inner.tsx` (ContextMenu integration).
+- **Combobox/Search**: The `combobox` prop allows composing a searchable select box.
+
+## Type Signatures
+
+```typescript
+export interface Option {
+  value: string | number;
+  label: string;
+  description?: string;
+  icon?: string;
+  disabled?: boolean;
+}
+
+export interface OptGroup {
+  label: string;
+  options: Option[];
+}
+
+export type SelectValue<Multiple extends boolean = false> =
+  Multiple extends true ? string[] : string;
+
+export type SelectChangeEvent<Multiple extends boolean = false> =
+  | React.ChangeEvent<HTMLSelectElement>
+  | { target: { value: SelectValue<Multiple> } };
+
+export interface SelectProps<
+  Multiple extends boolean = false,
+> extends LabelSharedProps {
+  id?: string;
+  value?: SelectValue<Multiple>;
+  defaultValue?: SelectValue<Multiple>;
+  onChange?: (e: SelectChangeEvent<Multiple>) => void;
+  onInputChange?: (value: string) => void;
+  options?: (Option | OptGroup)[];
+  required?: boolean;
+  placeholder?: string;
+  lockAncestorScrollOnOpen?: boolean;
+  multiple?: Multiple;
+  combobox?: boolean | "inline" | "search";
+  disabled?: boolean;
+  readOnly?: boolean;
+}
+```
+
+## Example Code
+
+```tsx
+import Select from "@/packages/Components/Select/Select";
+import { useState } from "react";
+
+export default function SelectExample() {
+  const [value, setValue] = useState<string>("");
+
+  const options = [
+    { label: "Apple", value: "apple" },
+    { label: "Banana", value: "banana" },
+    { label: "Cherry", value: "cherry", disabled: true },
+  ];
+
+  return (
+    <Select
+      title="Select Fruit"
+      placeholder="Please select a fruit"
+      value={value}
+      onChange={(e) => setValue(e.target.value as string)}
+      options={options}
+    />
+  );
+}
+```

package/.agents/references/Components/Skeleton.md

@@ -0,0 +1,48 @@
+# Skeleton
+
+## Purpose
+
+The `Skeleton` component provides a visual placeholder to the user while data is loading, naturally conveying the loading state.
+
+## Usage Logic
+
+- **Sizing**: Specify `width`, `height`, or pass a font typography type (`Title1`, `Body`, etc.) to the `type` prop to automatically adjust the height to match the text size.
+- **Multiple Slots**: The `count` prop easily renders multiple lines of skeleton UI at once. Concise code without array mapping.
+
+## Type Signatures
+
+```typescript
+import type { UIKitSizeValue } from "../../Frameworks/_shared/sizing";
+import type { TextProps } from "../Text/Text.types";
+
+export interface SkeletonProps {
+  "data-color-mode"?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  width?: UIKitSizeValue;
+  height?: UIKitSizeValue;
+  count?: number;
+  type?: TextProps["type"];
+}
+```
+
+## Example Code
+
+```tsx
+import Skeleton from "@/packages/Components/Skeleton/Skeleton";
+
+export default function SkeletonExample() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+      {/* Single-line skeleton matching 'Headline' text height */}
+      <Skeleton type="Headline" width="50%" />
+
+      {/* Three-line skeleton matching 'Body' text height */}
+      <Skeleton type="Body" count={3} />
+
+      {/* Arbitrary-size skeleton */}
+      <Skeleton width="100px" height="100px" />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Spinner.md

@@ -0,0 +1,62 @@
+# Spinner
+
+## Purpose
+
+The `Spinner` component is a rotating animation icon that visually represents an in-progress process or loading state. It supports three different designs (`apple`, `material`, `wheel`).
+
+## Usage Logic
+
+- **Visual Type**: Choose one of `apple` (segmented), `material` (SVG track), or `wheel` (default rotating) designs via the `type` prop.
+- **Customization**: Fine-tune the spinner's appearance and rotation speed via `size`, `color`, `strokeWidth`, `duration`, etc.
+- **Accessibility**: Automatically sets `role="progressbar"` or appropriate `aria-label`, `aria-hidden` to indicate progress, ensuring screen reader accessibility.
+
+## Type Signatures
+
+```typescript
+import type { AriaRole, CSSProperties, SVGAttributes } from "react";
+import type { UIKitSizeValue } from "../../Frameworks/_shared/sizing";
+import type { ThemePaint } from "../../Frameworks/Theme/Theme.types";
+
+export interface SpinnerProps {
+  "data-color-mode"?: string;
+  "aria-hidden"?: boolean | "true" | "false";
+  "aria-label"?: string;
+  role?: AriaRole;
+  type?: "apple" | "material" | "wheel";
+  className?: string;
+  style?: CSSProperties;
+  size?: UIKitSizeValue;
+  strokeWidth?: number;
+  color?: ThemePaint;
+  opacity?: number;
+  duration?: number;
+  linecap?: SVGAttributes<SVGElement>["strokeLinecap"];
+}
+```
+
+## Example Code
+
+```tsx
+import Spinner from "@/packages/Components/Spinner/Spinner";
+
+export default function SpinnerExample() {
+  return (
+    <div style={{ display: "flex", gap: "20px", alignItems: "center" }}>
+      {/* Default Wheel spinner */}
+      <Spinner size={32} color="Blue" />
+
+      {/* Material Design style spinner */}
+      <Spinner
+        type="material"
+        size={32}
+        color="Red"
+        strokeWidth={3}
+        duration={1.5}
+      />
+
+      {/* Apple style spinner */}
+      <Spinner type="apple" size={32} color="Gray" />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Text.md

@@ -0,0 +1,73 @@
+# Text
+
+## Purpose
+
+The `Text` component is a text element for applying a unified typography system across the project. It allows applying consistent font sizes, heights, and styles.
+
+## Usage Logic
+
+- **Typography Tokens**: Pass a UIKit typography hierarchy (`LargeTitle`, `Body`, `Caption1`, etc.) to `type` to easily apply predefined formatting.
+- **Styling Details**: Override `weight`, `color`, `textAlign`, `opacity`, `lineHeight`, etc.
+- **Vertical Trim**: With `verticalTrim={true}`, `lineHeight: 1` is applied, removing top/bottom text margins for precise layout calculation.
+
+## Type Signatures
+
+```typescript
+import type { UIKitSizeValue } from "../../Frameworks/_shared/sizing";
+import type { ThemePaint } from "../../Frameworks/Theme/Theme.types";
+
+export interface TextProps {
+  "data-color-mode"?: string;
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+  type?:
+    | "LargeTitle"
+    | "Title1"
+    | "Title2"
+    | "Title3"
+    | "Headline"
+    | "Callout"
+    | "Body"
+    | "Subheadline"
+    | "Footnote"
+    | "Caption1"
+    | "Caption2"
+    | "Coding"
+    | "Pre";
+  color?: ThemePaint;
+  lineHeight?: number;
+  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  letterSpacing?: number;
+  size?: UIKitSizeValue;
+  verticalTrim?: boolean;
+  fontType?: "serif" | "code";
+  textAlign?: "left" | "center" | "right";
+  id?: string;
+  opacity?: number;
+}
+```
+
+## Example Code
+
+```tsx
+import Text from "@/packages/Components/Text/Text";
+
+export default function TextExample() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "10px" }}>
+      <Text type="LargeTitle" weight={700} color="Base1">
+        Page Title
+      </Text>
+
+      <Text type="Body" color="Base2">
+        This is a standard body text that describes the contents of the page.
+      </Text>
+
+      <Text type="Caption1" color="Base3" textAlign="center">
+        Footer description
+      </Text>
+    </div>
+  );
+}
+```

package/.agents/references/Components/TimePicker.md

@@ -0,0 +1,72 @@
+# TimePicker
+
+## Purpose
+
+The `TimePicker` component is an input field that lets users select a time by directly entering hours, minutes, (optionally seconds and AM/PM) or adjusting via arrow keys.
+
+## Usage Logic
+
+- **Interaction**: Supports precise keyboard navigation within the input field via number keys, arrow keys (`ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`), tab key, etc.
+- **Time Format**: `showSeconds` determines whether to display seconds, and `use12h` selects between 12-hour (AM/PM display) and 24-hour formats.
+- **Component Architecture**: Composed of `TimePicker.core.tsx` (managing input and state) and `TimePicker.tsx` (handling layout/styling), abstracting complex focus-movement logic to improve usability. Covered in a single document integrated with the core logic.
+- **Controlled/Uncontrolled**: State is controlled via `value` and `defaultValue`. Time is handled as a string in `HH:mm` or `HH:mm:ss` format.
+
+## Type Signatures
+
+```typescript
+import type { LabelProps } from "../Label/Label.types";
+
+export interface TimePickerProps {
+  "data-color-mode"?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  title?: string;
+  required?: boolean;
+  readOnly?: boolean;
+  disabled?: boolean;
+  hint?: LabelProps["hint"];
+
+  value?: string;
+  defaultValue?: string;
+
+  showSeconds?: boolean;
+  use12h?: boolean;
+
+  placeholder?: string;
+  onChange?: (value: string) => void;
+  onHourOverflow?: (params: { input: number; normalized: number }) => void;
+}
+```
+
+## Example Code
+
+```tsx
+import TimePicker from "@/packages/Components/TimePicker/TimePicker";
+import { useState } from "react";
+
+export default function TimePickerExample() {
+  const [time, setTime] = useState("14:30");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "20px",
+        maxWidth: "300px",
+      }}
+    >
+      {/* Default 24-hour */}
+      <TimePicker title="Meeting Time" value={time} onChange={setTime} />
+
+      {/* 12-hour and with seconds */}
+      <TimePicker
+        title="Timer Setting"
+        use12h
+        showSeconds
+        defaultValue="02:15:30"
+      />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Timeline.md

@@ -0,0 +1,97 @@
+# Timeline
+
+## Purpose
+
+The `Timeline` component is a layout component that visualizes a series of events, states, or records as a time-ordered or sequential list.
+
+## Usage Logic
+
+- **Items structure**: Receives an array of `TimelineItemProps` structure via `items`. Each item includes text content (`children`), an icon (`icon`), or a custom node (`node`).
+- **Custom Nodes**: The node (dot) color or design can be customized globally (`nodePreset`, `nodeBackground`, `nodeColor`) or per item.
+- **Interactivity**: The inside of each item is wrapped with the `Pressable` component, so click/touch events can be easily bound via the `pressable` prop.
+
+## Type Signatures
+
+```typescript
+import type { IconProps } from "../Icon/Icon.types";
+import type { PressableProps } from "../../Frameworks/Pressable/Pressable.types";
+import type { ThemeSystemProps } from "../../Frameworks/Theme/Theme.types";
+
+export interface TimelineItemProps {
+  children?: React.ReactNode;
+  id?: string | number;
+  icon?: IconProps;
+  node?: React.ReactNode;
+  nodePreset?: ThemeSystemProps["themePreset"];
+  nodeBackground?: ThemeSystemProps["background"];
+  nodeColor?: ThemeSystemProps["color"];
+  pressable?: PressableProps;
+}
+
+export interface TimelineProps {
+  className?: string;
+  style?: React.CSSProperties;
+  items: TimelineItemProps[];
+  nodePreset?: ThemeSystemProps["themePreset"];
+  nodeBackground?: ThemeSystemProps["background"];
+  nodeColor?: ThemeSystemProps["color"];
+}
+```
+
+## Example Code
+
+```tsx
+import Timeline from "@/packages/Components/Timeline/Timeline";
+import Text from "@/packages/Components/Text/Text";
+
+export default function TimelineExample() {
+  const events = [
+    {
+      id: "1",
+      icon: { icon: "iCheck", size: 12 },
+      nodePreset: "UIPrimary",
+      children: (
+        <>
+          <Text type="Subheadline" weight={600}>
+            Order Completed
+          </Text>
+          <Text type="Caption1" color="Base3">
+            10:30 AM
+          </Text>
+        </>
+      ),
+    },
+    {
+      id: "2",
+      icon: { icon: "iTruck", size: 12 },
+      nodePreset: "UINeutral",
+      children: (
+        <>
+          <Text type="Subheadline" weight={600}>
+            In Delivery
+          </Text>
+          <Text type="Caption1" color="Base3">
+            2:15 PM
+          </Text>
+        </>
+      ),
+      pressable: {
+        onClick: () => alert("Go to delivery tracking page"),
+      },
+    },
+    {
+      id: "3",
+      nodePreset: "UISecondary", // gray dot indicating waiting state
+      children: (
+        <>
+          <Text type="Subheadline" weight={600} color="Base3">
+            Delivery Completed (Scheduled)
+          </Text>
+        </>
+      ),
+    },
+  ];
+
+  return <Timeline items={events as any} />;
+}
+```

package/.agents/references/Components/Title.md

@@ -0,0 +1,108 @@
+# Title
+
+## 1. Purpose
+
+A component for composing a UI title and related information (metadata, caption, action buttons, etc.). Used to render a header role or a section's main heading, and provides a `Title.ContextBar` sub-component that displays auxiliary actions and information to manage them integrally.
+
+## 2. Usage Logic
+
+- The `title` prop receives a single or multiple texts and elements.
+- Text-related styling options such as `titleType`, `fontType` can manipulate the title's appearance.
+- The `meta`, `caption`, `actions` props can arrange subtitles, additional info, and action buttons (icon groups).
+- `Title.ContextBar` (assign a `ContextBar` object) can place left/right-aligned context buttons and icons inside the title component or independently.
+
+## 3. Type Signatures
+
+```tsx
+export interface TitleProps {
+  "data-color-mode"?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  title?: TitleItemProps[] | TitleItemProps;
+  titleType?: TextProps["type"];
+  titleClassName?: TextProps["className"];
+  titleGap?: ViewProps["gap"];
+  leftGap?: ViewProps["gap"];
+  rightGap?: ViewProps["gap"];
+  fontType?: TextProps["fontType"];
+  titleLineHeight?: number;
+  titleVerticalTrim?: boolean;
+  suffix?: PillProps;
+  meta?: React.ReactNode;
+  actions?: IconGroupProps["icons"];
+  caption?: React.ReactNode;
+  captionOpacity?: TextProps["opacity"];
+  context?: React.ReactNode;
+}
+
+interface TitleItemProps {
+  "data-color-mode"?: string;
+  text?: React.ReactNode;
+  active?: boolean;
+  pressable?: PressableProps;
+}
+
+export interface TitleContextProps {
+  className?: string;
+  style?: React.CSSProperties;
+  start?: TitleContextItem | TitleContextItem[];
+  end?: TitleContextItem | TitleContextItem[];
+  startGap?: ViewProps["gap"];
+  endGap?: ViewProps["gap"];
+}
+
+export type TitleContextItem = Pick<
+  PressableProps,
+  | "className"
+  | "style"
+  | "themePreset"
+  | "background"
+  | "color"
+  | "themeInteractive"
+  | "selected"
+  | "border"
+  | "data-color-mode"
+> & {
+  key?: React.Key;
+  content: React.ReactNode;
+  leadingIcon?: IconProps["icon"];
+  trailingIcon?: IconProps["icon"];
+  leadingIconProps?: Omit<IconProps, "icon" | "pressable">;
+  trailingIconProps?: Omit<IconProps, "icon" | "pressable">;
+  pressable?: PressableProps;
+};
+```
+
+## 4. Example Code
+
+```tsx
+import Title from "./Title";
+import { IconBell, IconArrowLeft } from "lucide-react";
+
+function Example() {
+  return (
+    <Title
+      title={{ text: "Settings" }}
+      titleType="Title2"
+      caption="Manage your account settings"
+      meta="User Profile"
+      actions={[
+        {
+          icon: <IconBell />,
+          pressable: { onPress: () => alert("Notifications") },
+        },
+      ]}
+      context={
+        <Title.ContextBar
+          start={{
+            content: "Back",
+            leadingIcon: <IconArrowLeft />,
+            pressable: {},
+          }}
+          end={{ content: "Save", pressable: {} }}
+        />
+      }
+    />
+  );
+}
+```

package/.agents/references/Components/Toggle.md

@@ -0,0 +1,53 @@
+# Toggle
+
+## 1. Purpose
+
+A toggle (switch) component that lets the user switch between two states (on/off). Smoothly supports drag gestures and click animations.
+
+## 2. Usage Logic
+
+- Maintains accessibility by linking with the native HTML `input[type="checkbox"]`.
+- Supports both controlled and uncontrolled rendering via the `checked`, `defaultChecked` props.
+- Uses Framer Motion to naturally control the toggle button's drag (`drag="x"`) and spring animation.
+- Supports `loading`, `disabled`, `readOnly` states, displaying an internal spinner while loading.
+- Rendered together with a `title`, and the `titleSpaceBetween` prop easily sets the spacing layout between the toggle and title.
+
+## 3. Type Signatures
+
+```tsx
+export interface ToggleProps
+  extends
+    Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "color">,
+    ThemeSystemProps {
+  title?: string;
+  titleType?: TextProps["type"];
+  titleSpaceBetween?: boolean;
+  reversed?: boolean;
+  readOnly?: boolean;
+  loading?: boolean;
+  size?: UIKitSizeValue;
+  width?: UIKitSizeValue;
+  height?: UIKitSizeValue;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import { useState } from "react";
+import Toggle from "./Toggle";
+
+function Example() {
+  const [isEnabled, setIsEnabled] = useState(false);
+
+  return (
+    <Toggle
+      checked={isEnabled}
+      onChange={(e) => setIsEnabled(e.target.checked)}
+      title="Enable Feature"
+      titleSpaceBetween
+      size={24}
+    />
+  );
+}
+```