@musecat/uikit 0.1.1 → 0.1.3

package/.agents/references/Components/Box.md

@@ -0,0 +1,60 @@
+# Box
+
+## Purpose
+
+The Box component serves as a basic layout container for content. By combining an inner element (`Box.Content`) and a bottom area (`Box.Footer`), it can compose a consistent panel or card-shaped UI.
+
+## Usage Logic
+
+- `Box`: The base wrapper component, built on the View component, applying theme and layout properties.
+- `Box.Content`: The body area, which can embed a title, loading state, icon, etc., and notifies child elements via Context that they are inside the box.
+- `Box.Footer`: Located at the bottom of the Box, providing buttons (Pressable) or additional text. May include a divider (Divider).
+
+## Type Signatures
+
+```typescript
+interface BoxProps extends ThemeSystemProps, RadiusProps, BorderProps {
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+interface BoxContentProps {
+  children?: React.ReactNode;
+  title?: React.ReactNode;
+  titleSize?: TitleProps["titleType"];
+  icon?: IconProps;
+  loading?: boolean;
+  card?: boolean;
+  padding?: UIKitSizeValue;
+}
+
+interface BoxFooterProps extends ThemeSystemProps, BorderProps, RadiusProps {
+  children?: React.ReactNode;
+  title?: React.ReactNode;
+  pressable?: PressableProps;
+  divider?: DividerProps;
+}
+```
+
+## Example Code
+
+```tsx
+import Box from "@/packages/Components/Box/Box";
+
+export default function Example() {
+  return (
+    <Box themePreset="UIPrimary" border="Light" radius="Regular">
+      <Box.Content title="Information" loading={false}>
+        <p>This is the main content area.</p>
+      </Box.Content>
+      <Box.Footer
+        pressable={{ onClick: () => alert("Clicked!") }}
+        title="Action"
+      >
+        Confirm
+      </Box.Footer>
+    </Box>
+  );
+}
+```

package/.agents/references/Components/Button.md

@@ -0,0 +1,49 @@
+# Button
+
+## Purpose
+
+A versatile button component supporting various styles, icon placement, and asynchronous states (Promise).
+
+## Usage Logic
+
+- `Button` is built on Pressable and can express text, icons, and asynchronous results (loading/success/error) together.
+- The `iconEnd` prop or props like `modal`, `column` support various layouts (vertical arrangement, full-width modal button, etc.).
+- When a `promise` prop is given, it automatically renders loading and completion state icons and disables click events.
+
+## Type Signatures
+
+```typescript
+interface ButtonProps extends ThemeSystemProps, RadiusProps, BorderProps {
+  icon?: IconProps;
+  pressable?: PressableProps;
+  textType?: TextProps["type"];
+  sizeFull?: boolean;
+  promise?: {
+    type: "loading" | "success" | "error";
+    text?: React.ReactNode;
+  };
+  text?: React.ReactNode;
+  column?: boolean;
+  modal?: boolean;
+  iconEnd?: ButtonIconEndProps;
+  reversed?: boolean;
+}
+```
+
+## Example Code
+
+```tsx
+import Button from "@/packages/Components/Button/Button";
+
+export default function Example() {
+  return (
+    <Button
+      text="Submit"
+      themePreset="UIPrimary"
+      promise={{ type: "loading", text: "Loading..." }}
+      pressable={{ onClick: () => console.log("Submit") }}
+      icon={{ icon: "iCheck" }}
+    />
+  );
+}
+```

package/.agents/references/Components/Card.md

@@ -0,0 +1,67 @@
+# Card
+
+## Purpose
+
+A card component supporting basic information grouping and accordion (foldable) expansion.
+
+## Usage Logic
+
+- `Card`: Automatically branches to render `Card.default` or `Card.foldable` depending on the presence of the `accordion` prop.
+- `Card.default`: Can arrange title, caption, icon, a custom right-side component (`customRight`), and Pill tags horizontally or vertically.
+- `Card.foldable`: Includes an expand/collapse animation on click (using `motion/react`), and the open state can be controlled and synchronized via the `accordion` object. Also supports radius change animation.
+
+## Type Signatures
+
+```typescript
+interface CardBaseProps extends BorderProps, RadiusProps {
+  vertical?: boolean;
+  contained?: boolean;
+  pressable?: PressableProps;
+  title?: React.ReactNode;
+  caption?: React.ReactNode;
+  icon?: IconProps;
+  arrow?: IconProps | boolean;
+  pill?: PillProps[] | PillProps;
+  customRight?: React.ReactNode;
+}
+
+interface CardDefaultProps extends CardBaseProps, ThemeSystemProps {
+  accordion?: never;
+}
+
+interface CardFoldableProps extends Omit<
+  CardBaseProps,
+  "title" | "caption" | "vertical"
+> {
+  accordion: CardAccordionProps;
+  themePreset?: Stateful<ThemePreset>;
+  title?: Stateful<React.ReactNode>;
+  caption?: Stateful<React.ReactNode>;
+}
+
+type CardProps = CardDefaultProps | CardFoldableProps;
+```
+
+## Example Code
+
+```tsx
+import Card from "@/packages/Components/Card/Card";
+
+export default function Example() {
+  return (
+    <>
+      <Card
+        title="Static Card"
+        caption="Sub description"
+        icon={{ icon: "iInfo" }}
+      />
+      <Card
+        title={{ normal: "Expandable", activated: "Expanded!" }}
+        accordion={{ name: "group1", value: "item1" }}
+      >
+        <p>Hidden content revealed on click.</p>
+      </Card>
+    </>
+  );
+}
+```

package/.agents/references/Components/Checkbox.md

@@ -0,0 +1,48 @@
+# Checkbox
+
+## Purpose
+
+A checkbox element for receiving a boolean value from the user, with custom design and animation applied.
+
+## Usage Logic
+
+- Visually hides the native `<input type="checkbox">` and renders a designed checkbox using `Icon` and `View`.
+- Supports both controlled/uncontrolled components (`checked`, `defaultChecked`).
+- A label text can be composed via the `title` prop, and `reversed` swaps the order of the checkbox and text.
+
+## Type Signatures
+
+```typescript
+interface CheckboxProps
+  extends
+    Omit<
+      React.InputHTMLAttributes<HTMLInputElement>,
+      "size" | "title" | "color"
+    >,
+    BorderProps,
+    RadiusProps,
+    ThemeSystemProps {
+  title?: React.ReactNode;
+  titleType?: TextProps["type"];
+  titleSpaceBetween?: boolean;
+  reversed?: boolean;
+  size?: UIKitSizeValue;
+}
+```
+
+## Example Code
+
+```tsx
+import Checkbox from "@/packages/Components/Checkbox/Checkbox";
+
+export default function Example() {
+  return (
+    <Checkbox
+      title="Accept terms and conditions"
+      size={24}
+      onChange={(e) => console.log(e.target.checked)}
+      radius="ExtraLight"
+    />
+  );
+}
+```

package/.agents/references/Components/CodeBox.md

@@ -0,0 +1,31 @@
+# CodeBox
+
+## Purpose
+
+A component that displays code snippets with language syntax highlighting and includes a built-in code copy feature.
+
+## Usage Logic
+
+- Uses `PrismJS` to parse and highlight code. (HTML is injected internally.)
+- Automatically places the language name at the top and a copy button (`CodeBox.copy` module) according to the supported language.
+- Supports theme and layout (Radius, Border, etc.).
+
+## Type Signatures
+
+```typescript
+interface CodeBoxProps extends ThemeSystemProps, RadiusProps, BorderProps {
+  code: string;
+  language?: string;
+}
+```
+
+## Example Code
+
+```tsx
+import CodeBox from "@/packages/Components/CodeBox/CodeBox";
+
+export default function Example() {
+  const sampleCode = `const hello = 'world';\nconsole.log(hello);`;
+  return <CodeBox code={sampleCode} language="typescript" radius="Regular" />;
+}
+```

package/.agents/references/Components/ContextMenu.md

@@ -0,0 +1,82 @@
+# ContextMenu
+
+## Purpose
+
+A context menu that displays a list of menu items as a popover or bottom sheet (on mobile) and lets the user select an item.
+
+## Usage Logic
+
+- Built on the `Dialog` framework, it renders responsively as a popover or sheet depending on screen size (`isMobile`) and `mobileMode`.
+- Fully supports keyboard navigation (ArrowUp/Down, Home, End, Enter, Space), including a visual focus auto-scroll (Ensure Visible) logic.
+- Manages option items via the `contents` array, with individual items rendered by the submodule `ContextMenu.options.tsx`.
+
+## Type Signatures
+
+```typescript
+interface ContentItem {
+  type: "option";
+  value: string | number;
+  label: ReactNode;
+  icon?: string;
+  description?: string;
+  disabled?: boolean;
+  selected?: boolean;
+  onClick?: () => void;
+}
+
+interface ContextMenuProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  anchorRef: React.RefObject<HTMLElement | null>;
+  popoverOwnerId: string;
+  listId: string;
+  isInteractionDisabled: boolean;
+  contents: ContentItem[];
+  mobileMode?: DialogMobileMode;
+  showCheck?: boolean;
+}
+```
+
+## Example Code
+
+```tsx
+import ContextMenu from "@/packages/Components/ContextMenu/ContextMenu";
+import { useRef, useState } from "react";
+
+export default function Example() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLButtonElement>(null);
+
+  const options = [
+    {
+      type: "option" as const,
+      value: "1",
+      label: "Edit",
+      onClick: () => console.log("Edit"),
+    },
+    {
+      type: "option" as const,
+      value: "2",
+      label: "Delete",
+      onClick: () => console.log("Delete"),
+    },
+  ];
+
+  return (
+    <>
+      <button ref={ref} onClick={() => setOpen(true)}>
+        Open Menu
+      </button>
+      <ContextMenu
+        open={open}
+        onOpenChange={setOpen}
+        anchorRef={ref}
+        popoverOwnerId="example-menu"
+        listId="example-menu-list"
+        isInteractionDisabled={false}
+        contents={options}
+      />
+    </>
+  );
+}
+```

package/.agents/references/Components/ContributionGraph.md

@@ -0,0 +1,61 @@
+# ContributionGraph
+
+## 1. Purpose
+
+- A GitHub contribution-graph style visualization component.
+- Role: Maps daily activity data into 0~4 levels and displays the activity pattern over a period such as a year as a grid.
+
+## 2. Usage Logic
+
+- Receives an array of per-date activity objects via the `data` property.
+- Calculates the entire grid to display based on `endDate` and `visibleDays`; by default it shows the most recent 1 year (Rolling Year) from the end date.
+- Supports month titles, weekday labels, and left-right drag scrolling (including pointer/mouse-based touch scrolling).
+- Inherits `ThemeSystemProps` so design tokens like `themePreset`, `radius`, `border` can be injected externally.
+
+## 3. Type Signatures
+
+```typescript
+export interface ContributionActivity {
+  date: string | Date;
+  level: 0 | 1 | 2 | 3 | 4;
+  total_count?: number;
+  changelog_count?: number;
+  flag_count?: number;
+  legacy_ticket_count?: number;
+}
+
+export interface ContributionGraphProps
+  extends ThemeSystemProps, RadiusProps, BorderProps {
+  "data-color-mode"?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  data?: ContributionActivity[];
+  endDate?: string | Date;
+  visibleDays?: number;
+  locale?: string;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import ContributionGraph from "@/packages/Components/ContributionGraph/ContributionGraph";
+
+export default function Example() {
+  const data = [
+    { date: "2024-01-01", level: 3, total_count: 5 },
+    { date: "2024-01-02", level: 1, total_count: 1 },
+  ];
+
+  return (
+    <ContributionGraph
+      data={data}
+      endDate={new Date()}
+      visibleDays={365}
+      locale="ko"
+      themePreset="BaseFull"
+      radius="Regular"
+    />
+  );
+}
+```

package/.agents/references/Components/DatePicker.md

@@ -0,0 +1,92 @@
+# DatePicker
+
+## 1. Purpose
+
+- A date and time selection component.
+- Role: Provides a single date (`single`) or range (`range`) selection interface, with integrated time selection option (`showTime`). Supports both calendar selection via popover and direct editing of the input field.
+
+## 2. Usage Logic
+
+- **Component Separation**:
+  - `DatePicker.tsx`: Externally exposed wrapper. Combines the field (core) and popover calendar.
+  - `DatePicker.core.tsx`: Actual input field UI and keyboard manipulation (arrows, number input) logic.
+  - `DatePicker.calendar.tsx`: Grid-based calendar interface rendered inside the popover.
+  - `hooks/useCalendar.ts`: Calendar paging (prev/next month, year navigation).
+  - `hooks/useSelection.ts`: Single/range date selection state management.
+  - `DatePicker.utils.ts`: Date calculation and string parsing utilities.
+- **Mode Branching**: `mode="single"` (single date) or `mode="range"` (start-end range).
+- **Time Combination**: When `showTime=true`, a `TimePickerCore` is embedded as an independent input field separate from the calendar. The `use12h` option switches between 12/24-hour formats.
+- **Built-in Label**: Receives `LabelProps` such as `title`, `required`, `hint` to render a complete form element structure.
+
+## 3. Type Signatures
+
+```typescript
+export type DatePickerMode = "single" | "range";
+
+export interface DatePickerProps {
+  "data-color-mode"?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  title?: string;
+  required?: boolean;
+  readOnly?: boolean;
+  disabled?: boolean;
+  hint?: {
+    type: "info" | "error" | "warning" | "success";
+    text: React.ReactNode;
+  };
+
+  mode?: DatePickerMode;
+
+  // Single mode props
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string | null) => void;
+
+  // Range mode props
+  startDate?: string;
+  endDate?: string;
+  defaultStartDate?: string;
+  defaultEndDate?: string;
+  onRangeChange?: (start: string | null, end: string | null) => void;
+
+  placeholder?: string;
+  minDate?: string;
+  maxDate?: string;
+  disabledDaysOfWeek?: number[];
+
+  showTime?: boolean;
+  use12h?: boolean;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import DatePicker from "@/packages/Components/DatePicker/DatePicker";
+
+export default function Example() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "20px" }}>
+      {/* Single date selection */}
+      <DatePicker
+        mode="single"
+        title="Date of Birth"
+        defaultValue="1990-01-01"
+        onChange={(val) => console.log(val)}
+      />
+
+      {/* Range and time selection */}
+      <DatePicker
+        mode="range"
+        title="Event Period"
+        showTime
+        use12h
+        defaultStartDate="2024-05-01 10:00"
+        defaultEndDate="2024-05-07 18:00"
+        onRangeChange={(start, end) => console.log("Range:", start, end)}
+      />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Divider.md

@@ -0,0 +1,56 @@
+# Divider
+
+## 1. Purpose
+
+- A visual separator component within a layout.
+- Role: Renders a horizontal or vertical line to clearly mark structural separation between contents.
+
+## 2. Usage Logic
+
+- Default is a horizontal line (`width: 100%`, `height: 1px`). With `vertical=true`, it renders as a vertical line (`width: 1.5px`, `height: stretch`).
+- Controls surrounding margin size via `margin`, `marginVertical`, `marginHorizontal` props (mapped to `Size` token).
+- With `gradient=true`, renders a linear gradient that fades out at both ends (fade effect).
+- The default color is a semi-transparent version of `--color-base-reversed-6`, and `data-color-mode` can be injected.
+
+## 3. Type Signatures
+
+```typescript
+import type { UIKitSizeValue } from "../../Frameworks/_shared/sizing";
+
+export interface DividerProps {
+  "data-color-mode"?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  vertical?: boolean;
+  margin?: UIKitSizeValue;
+  marginHorizontal?: UIKitSizeValue;
+  marginVertical?: UIKitSizeValue;
+  gradient?: boolean;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import Divider from "@/packages/Components/Divider/Divider";
+
+export default function Example() {
+  return (
+    <div>
+      <span>Top content</span>
+
+      {/* Default horizontal divider */}
+      <Divider margin={16} />
+
+      <span>Bottom content</span>
+
+      {/* Gradient vertical divider */}
+      <div style={{ display: "flex", height: "50px" }}>
+        <span>Left</span>
+        <Divider vertical gradient marginHorizontal={8} />
+        <span>Right</span>
+      </div>
+    </div>
+  );
+}
+```

package/.agents/references/Components/Header.md

@@ -0,0 +1,52 @@
+# Header
+
+## 1. Purpose
+
+- A global or screen-level top navigation header component.
+- Role: Provides a `position: fixed` layout at the top and includes a background blur transition (`EdgeEffect`) by default.
+
+## 2. Usage Logic
+
+- Rendered fixed at the very top of the viewport (`top: 0`), applying a smooth overlay/blur fade effect on content scroll via the top EdgeEffect.
+- Inject ReactNodes into `left`, `center`, `right` props respectively to arrange items flexibly.
+- Controllable via separation of the inner content wrapper (`wrapperClassName`) and the top-level `<header>` (`className`).
+
+## 3. Type Signatures
+
+```typescript
+export interface HeaderProps {
+  "data-color-mode"?: string;
+  left?: React.ReactNode;
+  center?: React.ReactNode;
+  right?: React.ReactNode;
+  className?: string;
+  wrapperClassName?: string;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import Header from "@/packages/Components/Header/Header";
+import Icon from "@/packages/Components/Icon/Icon";
+import Text from "@/packages/Components/Text/Text";
+
+export default function Example() {
+  return (
+    <Header
+      left={
+        <Icon
+          icon="iArrowKeyLeft"
+          pressable={{ onClick: () => history.back() }}
+        />
+      }
+      center={
+        <Text type="Title3" weight={600}>
+          Screen Title
+        </Text>
+      }
+      right={<Icon icon="iSearch" />}
+    />
+  );
+}
+```

package/.agents/references/Components/Icon.md

@@ -0,0 +1,82 @@
+# Icon
+
+## 1. Purpose
+
+- An integrated rendering view for icons, images, loading spinners, and SVGs.
+- Role: Standardizes the output of icon font classes (`i*`), external image renderers, inline vectors (`SVG/data`), and the loading component (`Spinner`) under the same layout API.
+
+## 2. Usage Logic
+
+- 4 main modes:
+  - **Icon font**: Injected as `icon="iCheck"`, `iconBrand="iBrandApple"`.
+  - **Image**: Injected as `image="/path/to.jpg"` (uses Next.js Image wrapper).
+  - **SVG**: References an internal `SVG.data` like `svg="logo"`. The `svgBordered` prop allows custom stroke color.
+  - **Spinner**: Activated with `spinner=true` (SpinnerOptions can be passed).
+- With `box={true}`, it renders as a card-style icon with a rounded background. `boxOptions` controls details.
+- Injecting `pressable={{ onClick: ... }}` makes it immediately act as a button-style (interactive) icon wrapper.
+- `title` and `titleType` can attach a label (Text) next to the icon.
+
+## 3. Type Signatures
+
+```typescript
+export interface IconProps extends ThemeSystemProps, RadiusProps, BorderProps {
+  "data-color-mode"?: string;
+  className?: string;
+  innerClassName?: string;
+  style?: React.CSSProperties;
+  title?: React.ReactNode;
+
+  // Box wrapper mode
+  box?: boolean;
+  boxOptions?: { padding?: UIKitSizeValue; background?: ThemePaint /* ... */ };
+
+  // Size constraints
+  size?: UIKitSizeValue;
+  width?: UIKitSizeValue;
+  height?: UIKitSizeValue;
+
+  // Mode triggers
+  icon?: string;
+  iconBrand?: string;
+  iconFill?: boolean;
+  image?: string;
+  svg?: string;
+  svgBordered?:
+    boolean | { fill?: string; stroke?: string; strokeWidth?: number | string };
+  spinner?: boolean;
+
+  // Functionality
+  pressable?: PressableProps;
+  opacity?: number;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import Icon from "@/packages/Components/Icon/Icon";
+
+export default function Example() {
+  return (
+    <div style={{ display: "flex", gap: "10px" }}>
+      {/* 1. Normal icon font */}
+      <Icon icon="iSettings" size={24} color="Blue3" />
+
+      {/* 2. Interactive box-style brand icon */}
+      <Icon
+        iconBrand="iBrandGithub"
+        box
+        themePreset="UIPrimary"
+        pressable={{ onClick: () => alert("Github") }}
+      />
+
+      {/* 3. Loading state */}
+      <Icon spinner title="Loading..." titleType="Caption1" />
+
+      {/* 4. Vector graphic and image */}
+      <Icon svg="logo" width={64} height={64} />
+      <Icon image="https://example.com/avatar.png" box radius="Circle" />
+    </div>
+  );
+}
+```