@musecat/uikit 0.1.1 → 0.1.3

package/.agents/references/Components/Input.md

@@ -0,0 +1,60 @@
+# Input
+
+## 1. Purpose
+
+- A single text input form component.
+- Role: Combines the native HTML `input` element with the UIKit design system, theme props, and a Label (title, hint, etc.) wrapper.
+
+## 2. Usage Logic
+
+- Inherits standard input attributes like `type`, `value`, `placeholder`, `disabled`, `readOnly` as-is.
+- Passing `title`, `required`, `hint` props automatically wraps it internally with the `Label` component to render the title and validation message.
+- Supports the `prefix` prop: displays left-side text inside the input (e.g., `@`, `#`, `₩`, etc.).
+- On error, passing `hint={{ type: "error", text: "..." }}` automatically enables the ARIA-based `aria-invalid`.
+
+## 3. Type Signatures
+
+```typescript
+import type { LabelSharedProps } from "../Label/Label.types";
+
+export interface InputProps
+  extends
+    Omit<
+      React.InputHTMLAttributes<HTMLInputElement>,
+      "prefix" | keyof LabelSharedProps
+    >,
+    LabelSharedProps {
+  value?: string | number;
+  type?: string;
+  placeholder?: string;
+  prefix?: React.ReactNode;
+}
+```
+
+_(LabelSharedProps includes `title`, `required`, `hint`, ThemeSystemProps, etc.)_
+
+## 4. Example Code
+
+```tsx
+import Input from "@/packages/Components/Input/Input";
+
+export default function Example() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+      <Input
+        title="Email Address"
+        type="email"
+        placeholder="example@mail.com"
+        required
+      />
+
+      <Input
+        title="Nickname"
+        prefix="@"
+        placeholder="username"
+        hint={{ type: "error", text: "This nickname is already in use." }}
+      />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Label.md

@@ -0,0 +1,78 @@
+# Label
+
+## 1. Purpose
+
+- A form element container and control wrapper.
+- Role: Wraps input fields (Input, Select, DatePicker, etc.) and is responsible for the title, required marker (*), bottom hint (error, info, etc.) messages, and common outline styling (theme and padding).
+
+## 2. Usage Logic
+
+- Place the form control component to wrap inside `children`.
+- Wrapped by an outer `Pressable` wrapper so that clicking anywhere in the field area transfers focus to the inner form via `htmlFor` control.
+- Based on the `hint` object (`type`: "error", "success", "info", "warning", `text`), the bottom icon and text color are automatically mapped and rendered.
+- Frequently used internally to keep form interface specs consistent when creating or extending components.
+
+## 3. Type Signatures
+
+```typescript
+import type {
+  ThemeSystemProps,
+  BorderProps,
+  RadiusProps,
+} from "../../Frameworks/Theme/Theme.types";
+
+export interface LabelProps extends ThemeSystemProps, BorderProps, RadiusProps {
+  "data-color-mode"?: string;
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+
+  // HTML form attributes
+  htmlFor?: string;
+  hintId?: string;
+
+  // Content
+  title?: string;
+  required?: boolean;
+  hint?: {
+    type: "info" | "error" | "warning" | "success";
+    text: React.ReactNode;
+  };
+
+  // State
+  readOnly?: boolean;
+  disabled?: boolean;
+  cursor?: React.CSSProperties["cursor"];
+}
+
+// Omit 'children', 'htmlFor', 'hintId' for consumer forwarding
+export type LabelSharedProps = Omit<
+  LabelProps,
+  "children" | "htmlFor" | "hintId"
+>;
+```
+
+## 4. Example Code
+
+```tsx
+import Label from "@/packages/Components/Label/Label";
+import Checkbox from "@/packages/Components/Checkbox/Checkbox"; // virtual import
+
+export default function Example() {
+  return (
+    <Label
+      htmlFor="terms-agree"
+      title="Agree to Terms"
+      required
+      hint={{ type: "info", text: "Required to use the service." }}
+      themePreset="BaseFull"
+      radius="Regular"
+    >
+      <div style={{ display: "flex", gap: "8px", alignItems: "center" }}>
+        <Checkbox id="terms-agree" />
+        <span>I agree</span>
+      </div>
+    </Label>
+  );
+}
+```

package/.agents/references/Components/Layout.md

@@ -0,0 +1,102 @@
+# Layout Component Documentation
+
+## Purpose
+
+Acts as a container that establishes the common structure of applications and pages. Provides the base page layout (`Layout`), grid-based arrangement (`Layout.Grid`, `Layout.Section`), and a layout specialized for documents or posts (`DocsLayout`) to help build consistent UI composition and structure.
+
+## Usage Logic
+
+- **`Layout`**: Used as the top-level container of a page, composing the overall page frame via props such as `title`, `header`, `backgroundImage`, `children`.
+- **`Layout.Grid` & `Layout.Section`**: Used under `Layout` to split content into a grid (`Grid`) or group it into a specific area (`Section`) with a title.
+- **`Layout.docs`**: A dedicated layout for rendering document/post-style content such as a cover image, author info (profile), and creation date.
+
+## Type Signatures
+
+```tsx
+// Layout.types.ts
+export interface BackgroundImageValue {
+  height?: UIKitSizeValue;
+  src?: string;
+  filter?: CSSProperties["filter"];
+  margin?: BackgroundMarginValue;
+}
+
+export interface LayoutProps {
+  children?: React.ReactNode;
+  title?: React.ReactNode;
+  caption?: React.ReactNode;
+  titleType?: TitleProps["titleType"];
+  titleFontType?: TextProps["fontType"];
+  mobileTitleShown?: boolean;
+  header?: React.ReactNode;
+  backgroundImage?: string | BackgroundImageValue;
+  // ...
+}
+
+export interface LayoutGridViewProps {
+  children?: React.ReactNode;
+  ratio?: string;
+  gap?: ViewProps["gap"];
+  groupGap?: ViewProps["gap"];
+  // ...
+}
+
+export interface LayoutSectionProps extends ViewProps {
+  group?: string;
+  title?: React.ReactNode | TitleProps["title"];
+  titleType?: TitleProps["titleType"];
+  // ...
+}
+
+// Layout.docs.types.ts
+export interface DocsLayoutProps {
+  children?: React.ReactNode;
+  image?: string;
+  header?: React.ReactNode;
+  author?: ProfileProps;
+  createdBy?: string;
+  title?: React.ReactNode;
+  // ...
+}
+```
+
+## Example Code
+
+```tsx
+import Layout from "@/packages/Components/Layout/Layout";
+import DocsLayout from "@/packages/Components/Layout/Layout.docs";
+
+// Basic layout and section split
+export function MyPage() {
+  return (
+    <Layout
+      title="Dashboard"
+      backgroundImage={{ src: "/bg.png", height: "300px" }}
+    >
+      <Layout.Grid ratio="1fr 1fr" gap={16}>
+        <Layout.Section title="Recent News" titleType="Title2">
+          <div>News content 1</div>
+          <div>News content 2</div>
+        </Layout.Section>
+        <Layout.Section title="Statistics">
+          <div>Chart area</div>
+        </Layout.Section>
+      </Layout.Grid>
+    </Layout>
+  );
+}
+
+// Document-style layout
+export function MyPost() {
+  return (
+    <DocsLayout
+      title="Component Docs"
+      author={{ displayName: "Hong Gildong", avatarUrl: "..." }}
+      createdBy="2026-07-16"
+      image="/cover.png"
+    >
+      Document body content goes here.
+    </DocsLayout>
+  );
+}
+```

package/.agents/references/Components/Maps.md

@@ -0,0 +1,63 @@
+# Maps Component Documentation
+
+## Purpose
+
+A component (`MapOSM`) that renders a custom interactive map based on OpenStreetMap (OSM) using the `maplibre-gl` library. Provides core map-related UI/UX such as marker display, drag/zoom controls, and coordinate selection (click events).
+
+## Usage Logic
+
+- **`MapOSM`**: Injects `lat` (latitude) and `lon` (longitude) values to set the map's initial center and marker position. Map size is controlled via `width` and `height`.
+- When `interactive` mode is enabled, user zoom, panning, and rotation become available.
+- Providing the `onMapPick` callback lets you receive the coordinates (latitude, longitude) of the clicked location (usable as a coordinate picker).
+- Utility logic in `MapOSM.shared.ts` (`resolveSafeMapStyle`, etc.) safely applies style filters or controls the 3D view.
+
+## Type Signatures
+
+```tsx
+// MapOSM.types.ts
+import type maplibregl from "maplibre-gl";
+import type { CSSProperties } from "react";
+
+export interface MapOSMProps {
+  lat: number | string;
+  lon: number | string;
+  onMapPick?: (lat: number | string, lon: number | string) => void;
+  height?: string;
+  width?: string;
+  className?: string;
+  style?: CSSProperties;
+  mapClassName?: string;
+  mapStyle?: CSSProperties;
+  interactive?: boolean; // whether zoom/drag is enabled
+  disable3D?: boolean; // disable 3D terrain
+  showNavigationControl?: boolean; // show navigation control (top-right zoom control, etc.)
+  mapOptions?: Partial<maplibregl.MapOptions>;
+}
+```
+
+## Example Code
+
+```tsx
+import MapOSM from "@/packages/Components/Maps/OSM/MapOSM";
+import { useState } from "react";
+
+export function LocationPicker() {
+  const [location, setLocation] = useState({ lat: 37.5665, lon: 126.978 }); // Seoul City Hall default
+
+  return (
+    <div style={{ padding: "20px" }}>
+      <h3>Select Location</h3>
+      <MapOSM
+        lat={location.lat}
+        lon={location.lon}
+        height="500px"
+        interactive={true}
+        onMapPick={(lat, lon) => {
+          console.log(`Selected location: lat ${lat}, lon ${lon}`);
+          setLocation({ lat: Number(lat), lon: Number(lon) });
+        }}
+      />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Nav.md

@@ -0,0 +1,68 @@
+# Nav Component Documentation
+
+## Purpose
+
+Provides a UI for choosing one (or several) option among multiple choices such as tabs, radio button groups, and navigation menus. Supports a visual selection effect (sliding indicator) along with a smooth item selection method via drag-and-drop gestures.
+
+## Usage Logic
+
+- **`Nav` component**: Passes options (icon, text, value, etc.) via the `items` array to render the UI. Supports both Controlled (`value`, `onChange`) and Uncontrolled (`defaultValue`) modes.
+- **`useNavIndicator` (internal hook)**: Tracks the currently selected item's position and calculates `transform` and `width` so the highlight background (Indicator) moves smoothly.
+- **`useNavDrag` (internal hook)**: Manages the logic that, while dragging across buttons with mouse or touch (Drag Selection), dynamically changes the indicator to match the hovered value and commits the final selection at drop time.
+
+## Type Signatures
+
+```tsx
+// Nav.types.ts
+import type { ReactNode } from "react";
+import type { PressableProps } from "../../Frameworks/Pressable/Pressable.types";
+import type { IconProps } from "../Icon/Icon.types";
+
+export interface NavOption extends Omit<PressableProps, "title"> {
+  checked?: boolean;
+  icon?: IconProps;
+  title?: ReactNode;
+  value?: string | number; // value returned/compared on selection
+}
+
+export interface NavProps extends RadiusProps {
+  className?: string;
+  name?: string; // radio group name
+  radio?: boolean; // enable radio mode (exclusive single selection when true)
+  dragSelection?: boolean; // allow selection change via drag
+  dragSelectionCommit?: "change" | "end";
+  value?: string | number;
+  defaultValue?: string | number;
+  onChange?: (value: string | number) => void;
+  items: NavOption[];
+  // ...sizing and theme props
+}
+```
+
+## Example Code
+
+```tsx
+import Nav from "@/packages/Components/Nav/Nav";
+import { useState } from "react";
+
+export function TabNavigation() {
+  const [activeTab, setActiveTab] = useState<string>("home");
+
+  const items = [
+    { title: "Home", value: "home", icon: { icon: "iHome" } },
+    { title: "Explore", value: "explore", icon: { icon: "iSearch" } },
+    { title: "Profile", value: "profile", icon: { icon: "iPerson" } },
+  ];
+
+  return (
+    <Nav
+      radio={true}
+      dragSelection={true}
+      value={activeTab}
+      onChange={(val) => setActiveTab(val as string)}
+      items={items}
+      radius="Round"
+    />
+  );
+}
+```

package/.agents/references/Components/Pagination.md

@@ -0,0 +1,67 @@
+# Pagination Component Documentation
+
+## Purpose
+
+A pagination controller that helps navigate data or lists split across multiple pages. Along with previous/next and first/last navigation buttons, it provides an `input` area where users can directly enter a desired page number to jump quickly.
+
+## Usage Logic
+
+- **`Pagination`**: Receives `page` (current page) and `total` (total page count) props to compose the navigation bar.
+- Internally manages an `input` field for numeric entry, applying a debounce timer (350ms) so it does not jump immediately while the user is typing, but waits for input completion (or Enter key) before firing the `onChange` event.
+- Invalid page input is automatically clamped to the minimum (1) or maximum (`total`) value.
+- For i18n, internally uses the `Word()` hook to provide default labels ("Previous", "Next", etc.), and custom labels can also be injected directly.
+
+## Type Signatures
+
+```tsx
+// Pagination.types.ts
+import type {
+  BorderProps,
+  ThemeSystemProps,
+} from "../../Frameworks/Theme/Theme.types";
+
+export interface PaginationProps extends ThemeSystemProps, BorderProps {
+  page: number; // currently selected page number
+  total: number; // total page count (last page number)
+  onChange?: (page: number) => void; // page move event callback
+  disabled?: boolean; // disable the entire component
+
+  // Label customization (optional)
+  previousLabel?: string;
+  nextLabel?: string;
+  navigationLabel?: string;
+  getPageLabel?: (page: number, isCurrent: boolean) => string;
+
+  className?: string;
+  style?: React.CSSProperties;
+}
+```
+
+## Example Code
+
+```tsx
+import Pagination from "@/packages/Components/Pagination/Pagination";
+import { useState } from "react";
+
+export function DataList() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const totalPages = 25;
+
+  return (
+    <div style={{ padding: "20px" }}>
+      <ul>
+        {/* Render data list logic matching the current page */}
+        <li>Item 1</li>
+        <li>Item 2</li>
+      </ul>
+
+      <Pagination
+        page={currentPage}
+        total={totalPages}
+        onChange={(newPage) => setCurrentPage(newPage)}
+        themePreset="UIPrimary"
+      />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Pill.md

@@ -0,0 +1,75 @@
+# Pill Component Documentation
+
+## Purpose
+
+A UI element (capsule/pill shape) used as a keyword, tag, status badge, or small rounded capsule button. Flexibly supports combinations of icon and text, loading state display, and text ellipsis handling.
+
+## Usage Logic
+
+- Built on the `Pressable` framework component, so it easily converts from a simple badge form to a touch/clickable interactive button.
+- `text`, `icon`, `rightIcon` make it easy to arrange a left icon, center text, and right supplementary icon.
+- When the `loading` prop is true, a loading spinner icon is automatically shown in the right area.
+- The `ellipsis` option truncates text with `...` without wrapping in narrow spaces.
+
+## Type Signatures
+
+```tsx
+// Pill.types.ts
+import type { IconProps } from "../Icon/Icon.types";
+import type { PressableProps } from "../../Frameworks/Pressable/Pressable.types";
+import type { TextProps } from "../Text/Text.types";
+import type { RadiusProps } from "../../Frameworks/Theme/Radius.types";
+import type {
+  ThemeSystemProps,
+  BorderProps,
+} from "../../Frameworks/Theme/Theme.types";
+
+export interface PillProps extends ThemeSystemProps, RadiusProps, BorderProps {
+  text?: React.ReactNode;
+  icon?: IconProps; // left icon
+  rightIcon?: IconProps; // right icon
+
+  pressable?: PressableProps; // Pressable props including click events
+  disabled?: boolean;
+  loading?: boolean; // enable loading state (show spinner)
+
+  ellipsis?: boolean; // text ellipsis handling
+  shouldWrapText?: boolean; // whether to wrap text (default true)
+
+  textType?: TextProps["type"];
+  textSize?: TextProps["size"];
+  textWeight?: TextProps["weight"];
+  iconSize?: UIKitSizeValue;
+
+  checkedThemePreset?: ThemeSystemProps["themePreset"];
+  // ... other style and layout related Props
+}
+```
+
+## Example Code
+
+```tsx
+import Pill from "@/packages/Components/Pill/Pill";
+
+export function TagList() {
+  return (
+    <div style={{ display: "flex", gap: "8px" }}>
+      {/* Basic text pill */}
+      <Pill text="Design" themePreset="BaseFull" radius="Round" />
+
+      {/* Pill with icon, clickable */}
+      <Pill
+        text="Apply Filter"
+        icon={{ icon: "iFilter" }}
+        themePreset="BlueSolid"
+        pressable={{
+          onClick: () => console.log("Filter clicked"),
+        }}
+      />
+
+      {/* Loading state pill */}
+      <Pill text="Saving" loading={true} disabled={true} />
+    </div>
+  );
+}
+```

package/.agents/references/Components/Profile.md

@@ -0,0 +1,76 @@
+# Profile Component Documentation
+
+## Purpose
+
+A component that summarizes and renders a user's profile information (name, avatar, identifier, badge, affiliation role, etc.). In addition to fallback image (default icon) handling based on avatar presence, it also includes an advanced feature that displays expanded profile info in a popover layer on click.
+
+## Usage Logic
+
+- **Inline rendering (`ProfileInlineContent`)**: Shows the most basic profile form exposed externally. Renders the avatar photo, name (`displayName`), sub-text (`username`), and certification mark (Certified).
+- **Popover rendering (`ProfilePopoverContent`)**: When `profileHref` or the `popover` prop is passed, a detailed info popover is shown on click/hover. This may include extended actions such as join date, detailed Role list, and user report (`canReport`).
+- **Shared logic (`Profile.shared.ts`)**: Provides the `getProfileAvatarIconProps` utility function, which, when an actual profile image URL (`avatarUrl`) exists, generates that image, and otherwise generates the default person icon (`iPerson`) with appropriate size and padding.
+
+## Type Signatures
+
+```tsx
+// Profile.types.ts
+export type ProfileRole = {
+  label: string;
+  color?: ThemePaint;
+  icon?: string;
+  iconFill?: boolean;
+};
+
+export type ProfileSizeOptions = {
+  avatar?: number; // avatar size
+  textType?: TextProps["type"];
+  textSize?: UIKitSizeValue;
+  badge?: number; // badge (certification) size
+  gap?: UIKitSizeValue;
+  fallbackPadding?: UIKitSizeValue; // padding when using default icon
+};
+
+export interface ProfileProps {
+  displayName: string;
+  username?: string;
+  avatarUrl?: string | null;
+  avatarLoading?: "eager" | "lazy";
+  bio?: string;
+  isCertified?: boolean; // presence of official certification mark
+  certifiedAt?: string;
+  roles?: ProfileRole[]; // user's multiple roles list
+  joinedAtText?: string;
+
+  profileHref?: string | null; // URL to navigate to on popover click
+  canReport?: boolean; // whether report feature is enabled
+  onReport?: () => void;
+
+  extended?: boolean; // enable inline display of supplementary info like username
+  size?: ProfileSizeOptions;
+  popover?: React.ReactNode; // inject custom popover content
+}
+```
+
+## Example Code
+
+```tsx
+import Profile from "@/packages/Components/Profile/Profile";
+
+export function UserHeader() {
+  return (
+    <Profile
+      displayName="Kim Coding"
+      username="kim_code"
+      avatarUrl="https://example.com/avatar.png"
+      isCertified={true}
+      bio="Frontend developer."
+      joinedAtText="Joined 2023"
+      roles={[{ label: "Admin", color: "Blue3" }]}
+      profileHref="/users/kim_code"
+      canReport={true}
+      onReport={() => console.log("Report user")}
+      extended={true} // expose username (@kim_code) even inline
+    />
+  );
+}
+```

package/.agents/references/Components/Progress.md

@@ -0,0 +1,72 @@
+# Progress Component Documentation
+
+## Purpose
+
+A linear progress bar component that visualizes task progress as a percentage. It can also render an indeterminate spinner-style infinite loading state for tasks with unknown duration.
+
+## Usage Logic
+
+- **Determinate state**: When `value`, `min`, `max` are passed, the progress rate (percentage) is calculated by the formula `(value - min) / (max - min) * 100`, adjusting the width of the inner indicator view (using the `--progress-percent` CSS variable).
+- **Indeterminate state**: When `indeterminate={true}` is set, instead of a percentage-based progress bar, the inner `Spinner` component is rendered directly to indicate an infinite loading state.
+- Value clamping: Even if the passed `value` is out of range, it is safely adjusted between `min` and `max` automatically.
+
+## Type Signatures
+
+```tsx
+// Progress.types.ts
+import { RadiusProps } from "@/packages/Frameworks/Theme/Radius.types";
+import type {
+  ThemeBackgroundPaint,
+  ThemePaint,
+} from "../../Frameworks/Theme/Theme.types";
+
+export interface ProgressProps extends RadiusProps {
+  value?: number; // current progress value (default: 0)
+  min?: number; // minimum value (default: 0)
+  max?: number; // maximum value (default: 100)
+  indeterminate?: boolean; // whether in indeterminate (infinite loading) state
+
+  background?: ThemeBackgroundPaint; // track (background) color theme
+  color?: ThemePaint; // indicator (progress bar) color theme
+
+  className?: string;
+  trackClassName?: string;
+  indicatorClassName?: string;
+}
+```
+
+## Example Code
+
+```tsx
+import Progress from "@/packages/Components/Progress/Progress";
+
+export function FileUploadStatus({
+  progressPercentage,
+  isUploading,
+  isPreparing,
+}) {
+  // Preparing, so total length unknown (indeterminate state)
+  if (isPreparing) {
+    return <Progress indeterminate={true} />;
+  }
+
+  // Uploading (determinate state)
+  if (isUploading) {
+    return (
+      <div style={{ width: "300px" }}>
+        <span>Uploading: {progressPercentage}%</span>
+        <Progress
+          value={progressPercentage}
+          min={0}
+          max={100}
+          color="BlueSolid"
+          background="Base6TP6"
+          radius="Round"
+        />
+      </div>
+    );
+  }
+
+  return <span>Upload complete</span>;
+}
+```