@musecat/uikit 0.1.1 → 0.1.2

package/.agents/references/Components/Tooltip.md

@@ -0,0 +1,62 @@
+# Tooltip
+
+## 1. Purpose
+
+A component that displays a popup bubble (`content`) with additional explanation or information when hovering over or focusing a specific UI element (`trigger`).
+
+## 2. Usage Logic
+
+- Positions the `content` popup above the React element passed as `trigger`.
+- Built-in position auto-adjustment (clamp and flip) logic calculates and adjusts (ClampShift) the position so it is not clipped at screen edges.
+- The `placement` prop specifies the bubble's default position and alignment direction (default: `"top"`).
+- The `delay` prop adjusts the delay before the tooltip appears on hover.
+- Flexible controlled and uncontrolled usage via `open`, `defaultOpen`, `onOpenChange`.
+- Setting `interactive` to `true` keeps the bubble from disappearing immediately when the mouse moves over it, enabling interaction.
+
+## 3. Type Signatures
+
+```tsx
+export type TooltipPlacement =
+  "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end";
+
+export interface TooltipProps extends BorderProps {
+  trigger: React.ReactNode;
+  content: React.ReactNode;
+  placement?: TooltipPlacement;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  delay?: number;
+  disabled?: boolean;
+  interactive?: boolean;
+  flip?: boolean;
+  className?: string;
+  contentClassName?: string;
+  maxWidth?: number | string;
+
+  themePreset?: ThemePreset;
+  background?: ThemeBackgroundPaint;
+  color?: ThemePaint;
+  radius?: RadiusValue;
+
+  "data-color-mode"?: string;
+}
+```
+
+## 4. Example Code
+
+```tsx
+import Tooltip from "./Tooltip";
+import Pressable from "../../Frameworks/Pressable/Pressable";
+
+function Example() {
+  return (
+    <Tooltip
+      placement="top"
+      content="This is some additional information."
+      delay={300}
+      trigger={<Pressable>Hover me</Pressable>}
+    />
+  );
+}
+```

package/.agents/references/Frameworks/DNDView.md

@@ -0,0 +1,82 @@
+# DNDView Framework
+
+## Purpose
+
+`DNDView` is a component that provides list reordering (Reorder) via drag-and-drop (DnD). Internally uses `@dnd-kit/core` and `@dnd-kit/sortable`, fully supporting mouse, touch, and keyboard accessibility.
+
+## Usage Logic
+
+- Provide an `items` array and a `getKey` function to uniquely identify them.
+- Define each item's appearance via the `renderItem` function; rendering the `handle` property from the `state` argument passed in makes that area the drag handle.
+- When order changes, the `onReorder(newItems)` callback is called, so update state in the parent component.
+- The `strategy` prop selects the sorting algorithm (`vertical`, `horizontal`, `rect`), and keyboard navigation is optimized for direction-key movement per this strategy.
+
+## Type Signatures
+
+```typescript
+import type { UniqueIdentifier } from "@dnd-kit/core";
+import type { ReactNode } from "react";
+
+export type DNDViewItemState<T> = {
+  item: T;
+  id: UniqueIdentifier;
+  index: number;
+  dragging: boolean;
+  sorting: boolean;
+  handle: ReactNode;
+};
+
+export type DNDViewStrategy = "vertical" | "horizontal" | "rect";
+
+export interface DNDViewProps<T> extends ViewProps {
+  items: T[];
+  onReorder: (items: T[]) => void;
+  getKey: (item: T) => UniqueIdentifier;
+  renderItem: (item: T, state: DNDViewItemState<T>) => ReactNode;
+  renderHandle?: (
+    props: HTMLAttributes<HTMLElement>,
+    state: DNDViewItemState<T>,
+  ) => ReactNode;
+  dragHandle?: boolean;
+  keyboard?: boolean;
+  strategy?: DNDViewStrategy;
+}
+```
+
+## Example Code
+
+```tsx
+import View from "@/packages/Frameworks/View";
+import { useState } from "react";
+
+function SortableList() {
+  const [items, setItems] = useState([
+    { id: "1", name: "Item 1" },
+    { id: "2", name: "Item 2" },
+    { id: "3", name: "Item 3" },
+  ]);
+
+  return (
+    <View.DND
+      items={items}
+      getKey={(item) => item.id}
+      onReorder={setItems}
+      strategy="vertical"
+      gap={8}
+      renderItem={(item, { dragging, handle }) => (
+        <View
+          row
+          alignItems="center"
+          padding={16}
+          radius="R8"
+          background="Base1"
+          shadow={dragging ? "Bold" : "None"} // emphasize while dragging
+        >
+          {handle} {/* Grab and drag this part */}
+          <span style={{ marginLeft: 16 }}>{item.name}</span>
+        </View>
+      )}
+    />
+  );
+}
+```

package/.agents/references/Frameworks/Dialog.md

@@ -0,0 +1,109 @@
+# Dialog Framework
+
+## Purpose
+
+The `Dialog` framework is a universal framework that centrally manages all overlay UI such as popover, modal, sheet, and funnel. It supports both a global-state-based imperative API (`dialog(...)`) and a declarative component (`<Dialog />`).
+
+## Usage Logic
+
+- **Imperative**: Call `dialog.modal({ ... })` or `dialog.popover(element, { ... })` to render a dialog from anywhere. (Mounting `<DialogBootstrap />` somewhere in the app root is required)
+- **Declarative**: Declare inside a component's JSX as `<Dialog open={isOpen} onOpenChange={setIsOpen} mode="modal" ... />`.
+- **Per-mode characteristics**:
+  - `popover`: Positioned around a specific element (`anchorRef`).
+  - `modal`: A traditional modal positioned at the center of the screen.
+  - `sheet`: A Bottom Sheet that rises from the bottom on mobile. (Supports gestures, snap points)
+  - `mobileMode`: A useful option that is `modal` on desktop but automatically converts to `sheet` on mobile (when `isMobile` condition is met).
+- **Common components**: Header, Footer (button arrangement automation), background (Dim), exit animation handling, keyboard Escape handling, etc.
+
+## Type Signatures
+
+```typescript
+import type { ReactNode, RefObject } from "react";
+import type {
+  PopoverConfig,
+  ModalConfig,
+  SheetConfig,
+  FunnelConfig,
+  ExitConfig,
+} from "./Dialog.types";
+import type { ThemeSystemProps, BorderProps } from "../Theme/Theme.types";
+import type { RadiusProps } from "../Theme/Radius.types";
+
+export type DialogMode = "popover" | "modal" | "sheet";
+export type DialogMobileMode = "modal" | "sheet";
+
+// Shared by all mode configs
+type DialogBaseConfig = ThemeSystemProps & BorderProps & RadiusProps;
+
+export interface DialogProps {
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  id?: string;
+  mode: DialogMode;
+  mobileMode?: DialogMobileMode;
+
+  // Per-mode config (choose one)
+  popover?: PopoverConfig;
+  modal?: ModalConfig;
+  sheet?: SheetConfig;
+  funnel?: FunnelConfig; // multi-step funnel flow control
+
+  content?: ReactNode; // dialog body
+  exit?: ExitConfig; // outside click, cancel button behavior
+}
+
+// Imperative API
+export function dialog(props: DialogProps): DialogInstance;
+dialog.modal = (props: Omit<DialogProps, "mode">) => DialogInstance;
+dialog.sheet = (props: Omit<DialogProps, "mode">) => DialogInstance;
+dialog.popover = (anchor: HTMLElement, props: Omit<DialogProps, "mode">) =>
+  DialogInstance;
+```
+
+## Example Code
+
+```tsx
+import Dialog, { dialog } from "@/packages/Frameworks/Dialog/Dialog";
+import Pressable from "@/packages/Frameworks/Pressable";
+import { useState } from "react";
+
+function Example() {
+  const [open, setOpen] = useState(false);
+
+  // 1. Imperative modal call
+  const showModal = () => {
+    dialog.modal({
+      modal: {
+        header: { title: "Imperative Modal" },
+        footer: {
+          buttons: [{ text: "Confirm", onClick: (e, close) => close() }],
+        },
+      },
+      content: <div>This modal can be called from anywhere.</div>,
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={showModal}>Open Imperative Modal</button>
+      <button onClick={() => setOpen(true)}>Open Declarative Sheet</button>
+
+      {/* 2. Declarative sheet rendering */}
+      <Dialog
+        mode="sheet"
+        open={open}
+        onOpenChange={setOpen}
+        sheet={{
+          header: { title: "Select Option" },
+          snapPoints: [300, 600],
+        }}
+      >
+        <div style={{ padding: 20 }}>
+          <Pressable>Menu 1</Pressable>
+          <Pressable>Menu 2</Pressable>
+        </div>
+      </Dialog>
+    </div>
+  );
+}
+```

package/.agents/references/Frameworks/EdgeEffect.md

@@ -0,0 +1,64 @@
+# EdgeEffect Framework
+
+## Purpose
+
+The `EdgeEffect` framework adds a blurry gradient overlay to a specific directional edge (top, bottom, left, right) of a container, providing a visual effect where the inner content fades out smoothly at both ends of the screen.
+
+## Usage Logic
+
+- Rendered on top of the `View` component and mainly used to apply a gradient to the edge of a scrollable element.
+- Specifying one of `"left"`, `"right"`, `"top"`, `"bottom"` for the `side` prop spreads the gradient toward the opposite direction of that side.
+- `pointerEvents: "none"` is applied by default so it does not interfere with click/touch events.
+
+## Type Signatures
+
+```typescript
+import type { ViewProps } from "../View/View.types";
+
+export interface EdgeEffectProps extends Omit<ViewProps, "children"> {
+  side?: "left" | "right" | "top" | "bottom";
+}
+```
+
+## Example Code
+
+```tsx
+import EdgeEffect from "@/packages/Frameworks/EdgeEffect";
+import View from "@/packages/Frameworks/View";
+
+function ScrollContainer() {
+  return (
+    <View style={{ position: "relative", height: 300, overflow: "hidden" }}>
+      {/* Top edge fade effect */}
+      <EdgeEffect
+        side="top"
+        style={{
+          position: "absolute",
+          top: 0,
+          left: 0,
+          right: 0,
+          height: 40,
+          zIndex: 10,
+        }}
+      />
+
+      <View style={{ overflowY: "auto", height: "100%" }}>
+        {/* contents... */}
+      </View>
+
+      {/* Bottom edge fade effect */}
+      <EdgeEffect
+        side="bottom"
+        style={{
+          position: "absolute",
+          bottom: 0,
+          left: 0,
+          right: 0,
+          height: 40,
+          zIndex: 10,
+        }}
+      />
+    </View>
+  );
+}
+```

package/.agents/references/Frameworks/HScrollView.md

@@ -0,0 +1,76 @@
+# HScrollView Framework
+
+## Purpose
+
+`HScrollView` is a horizontal scroll container supporting both mobile and desktop environments. Internally uses `embla-carousel-react` to provide a smooth horizontal scroll experience based on touch swipe and mouse wheel, and can automatically apply EdgeEffect at both ends.
+
+## Usage Logic
+
+- The `active` prop specifies whether scrolling is enabled. Passing a string-based viewport breakpoint ("w1", "w2", "w3", "w4") allows responsive activation of the swiper only below a specific breakpoint.
+- The carousel engine (Embla) is activated only when there are multiple child elements; with one or fewer, or when inactive, it falls back to a normal Flexbox structure.
+- The `renderControls` render prop can freely inject left/right scroll control buttons outside or inside the swiper.
+
+## Type Signatures
+
+```typescript
+import type { CSSProperties, ReactNode } from "react";
+import type { ViewProps } from "../View.types";
+
+export type HScrollViewViewport = "w1" | "w2" | "w3" | "w4";
+export type HScrollViewActive = boolean | HScrollViewViewport;
+
+export interface HScrollViewControls {
+  scrollPrev: () => void;
+  scrollNext: () => void;
+  canScrollPrev: boolean;
+  canScrollNext: boolean;
+  isScrollActive: boolean;
+}
+
+export interface HScrollViewProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "color"
+> {
+  active?: HScrollViewActive;
+  rootStyle?: CSSProperties;
+  containerStyle?: CSSProperties;
+  activeContainerStyle?: CSSProperties;
+  inactiveContainerStyle?: CSSProperties;
+  itemWidth?: number | string;
+  itemHeight?: number | string;
+  renderControls?: (controls: HScrollViewControls) => ReactNode;
+  showEdgeEffect?: boolean;
+  // ... ViewProps (gap, padding, margin, width, theme, etc.)
+}
+```
+
+## Example Code
+
+```tsx
+import HScrollView from "@/packages/Frameworks/View/HScrollView/HScrollView";
+import View from "@/packages/Frameworks/View";
+
+function HorizontalList() {
+  return (
+    <HScrollView
+      active="w3" // enable horizontal scroll only below 768px
+      gap={16}
+      showEdgeEffect={true}
+      itemWidth="20rem"
+    >
+      <View background="Base3" padding={24}>
+        Item 1
+      </View>
+      <View background="Base3" padding={24}>
+        Item 2
+      </View>
+      <View background="Base3" padding={24}>
+        Item 3
+      </View>
+      <View background="Base3" padding={24}>
+        Item 4
+      </View>
+    </HScrollView>
+  );
+}
+```

package/.agents/references/Frameworks/ImageView.md

@@ -0,0 +1,67 @@
+# ImageView Framework
+
+## Purpose
+
+The `ImageView` framework is a composite component that renders (single and multiple) images optimally and provides a full-screen or popup modal zoom/slide view (gallery) on click. Internally supports Next.js's `next/image`, and uses `embla-carousel` in slide mode.
+
+## Usage Logic
+
+- Passing a single string to `src` renders one image; passing an array (`string[]` or `ImageItem[]`) displays it as a horizontally scrolling gallery.
+- Passing the `dialog` prop opens an immersive image viewer as a modal based on the `Dialog` framework when the image is clicked.
+- Includes its own blur data generation utility (fallback blur) to provide a natural placeholder during loading.
+
+## Type Signatures
+
+```typescript
+export type ImageItem = {
+  id: number;
+  src: string;
+  alt: string;
+  srcDialog?: string; // high-quality image to show in dialog mode
+  blurDataURL?: string;
+};
+
+export interface ImageProps extends RadiusProps {
+  src: string | string[] | ImageItem[];
+  alt?: string | string[];
+  width?: number | string | (number | string)[];
+  height?: number | string | (number | string)[];
+  priority?: boolean;
+  groupWidth?: string;
+  groupHeight?: string;
+  groupGap?: number | string;
+  overlay?: ReactNode | ReactNode[];
+  control?: boolean | { left?: boolean; right?: boolean /* ... */ };
+  dialog?: {
+    overlay?: ReactNode | ReactNode[];
+    header?: { content?: ReactNode };
+    footer?: { list?: boolean; counter?: boolean /* ... */ };
+  };
+}
+```
+
+## Example Code
+
+```tsx
+import View from "@/packages/Frameworks/View";
+
+function PhotoGallery() {
+  const images = [
+    { id: 1, src: "/img1.jpg", alt: "Photo 1" },
+    { id: 2, src: "/img2.jpg", alt: "Photo 2" },
+  ];
+
+  return (
+    <ImageView
+      src={images}
+      radius="R12"
+      groupWidth="240px"
+      groupHeight="160px"
+      control={{ left: true, right: true }}
+      dialog={{
+        footer: { list: true, counter: true },
+      }}
+    />
+  );
+}
+```

package/.agents/references/Frameworks/Motion.md

@@ -0,0 +1,62 @@
+# Motion Framework
+
+## Purpose
+
+The `Motion` framework is used to provide consistent animation effects and transition presets within UIKit. It centrally manages `framer-motion` (or `motion/react`) configuration values mainly applied to motion-based interfaces such as modals, sheets, and popovers.
+
+## Usage Logic
+
+- `motionTransitions`: An object managing animation physical properties (stiffness, damping, mass, etc.). Defines default behaviors such as spring or tween.
+- `motionPresets`: Provides `initial`, `animate`, `exit` state definition objects or factory functions for specific UI components like modal, popover, and backdrop.
+
+## Type Signatures
+
+```typescript
+// Inside Motion.presets.ts
+
+export const motionTransitions = {
+  sheet: { snap, entrance, exit },
+  modal: { transition },
+  popover: { transition },
+  backdrop: { transition },
+};
+
+export const motionPresets = {
+  modal: { initial, animate, exit, transition },
+  popover: (isPositionReady: boolean) => ({
+    initial,
+    animate,
+    exit,
+    transition,
+  }),
+  backdrop: (open?: boolean) => ({ initial, animate, exit, transition }),
+};
+```
+
+## Example Code
+
+```tsx
+import { motion } from "motion/react";
+import { motionPresets } from "@/packages/Frameworks/Motion";
+
+function AnimatedModal({ isOpen, children }) {
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <>
+          {/* Backdrop animation */}
+          <motion.div
+            {...motionPresets.backdrop(isOpen)}
+            className="backdrop"
+          />
+
+          {/* Modal body animation */}
+          <motion.div {...motionPresets.modal} className="modal-content">
+            {children}
+          </motion.div>
+        </>
+      )}
+    </AnimatePresence>
+  );
+}
+```

package/.agents/references/Frameworks/Pressable.md

@@ -0,0 +1,79 @@
+# Pressable Framework
+
+## Purpose
+
+The `Pressable` framework is a versatile multipurpose wrapper component that handles user interactions such as click, touch, and hover. It dynamically identifies its role—link (`<a>`, `Link`), button (`<button>`), form control (`checkbox`, `radio`), or custom popover trigger—and renders the appropriate DOM element and accessibility attributes. It also uniformly applies Squircle shapes, motion wrapping, and theme-based styling.
+
+## Usage Logic
+
+- When an `href` prop is given, it internally renders as Next.js's `Link` component or a plain `<a>` tag.
+- With `type="checkbox"` or `type="radio"`, it renders as a custom label (`<label>`) together with a visually hidden `<input>` element.
+- With a button action or `onClick`, it renders as a `<button>`. The `popover` prop lets you declaratively write a popover trigger and inner content together.
+- Use `themePreset` etc. to automate styling for press/hover interactions.
+
+## Type Signatures
+
+```typescript
+import type { CSSProperties } from "react";
+import type { LinkProps } from "next/link";
+import type { MotionProps } from "motion/react";
+import type { PopoverConfig } from "../Dialog/Dialog.types";
+import type { WindProps } from "../_shared/Wind.types";
+import type { ThemeSystemProps, BorderProps } from "../Theme/Theme.types";
+import type { RadiusProps } from "../Theme/Radius.types";
+
+export interface PressableProps
+  extends WindProps, ThemeSystemProps, BorderProps, RadiusProps /* ...others omitted */ {
+  href?: LinkProps["href"];
+  onClick?: (e: React.MouseEvent) => void;
+  type?: HTMLButtonElement["type"] | "checkbox" | "radio";
+  disabled?: boolean;
+  checked?: HTMLInputElement["checked"];
+  popover?: Omit<PopoverConfig, "anchorRef"> & {
+    content: React.ReactNode;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+  };
+  motion?: MotionProps;
+  noSquircle?: boolean; // whether to prevent Squircle corner application
+  // other various event handlers and layout properties
+}
+```
+
+## Example Code
+
+```tsx
+import Pressable from "@/packages/Frameworks/Pressable/Pressable";
+
+function Example() {
+  return (
+    <div style={{ display: "flex", gap: 16 }}>
+      {/* 1. Normal button */}
+      <Pressable themePreset="UIPrimary" onClick={() => alert("Clicked")}>
+        Primary Button
+      </Pressable>
+
+      {/* 2. Link button */}
+      <Pressable href="/about" themePreset="BaseFull" radius="R16">
+        Go to About
+      </Pressable>
+
+      {/* 3. Checkbox control */}
+      <Pressable type="checkbox" checked={true} onChange={() => {}}>
+        Toggle Checked
+      </Pressable>
+
+      {/* 4. Popover trigger combined */}
+      <Pressable
+        themePreset="UISecondary"
+        popover={{
+          content: <div style={{ padding: 16 }}>This is popover content.</div>,
+        }}
+      >
+        Open Popover
+      </Pressable>
+    </div>
+  );
+}
+```

package/.agents/references/Frameworks/Squircle.md

@@ -0,0 +1,50 @@
+# Squircle Framework
+
+## Purpose
+
+The `Squircle` framework is a component for rendering the "Super Ellipse" (squircle) corners mainly used in the Apple ecosystem within React applications. Using the `figma-squircle` library, it dynamically calculates and applies an SVG Path-based `clip-path`, providing smooth and soft rounded-corner design.
+
+## Usage Logic
+
+- Renders as a `<div>` by default, and can be changed to the desired element via the `as` prop.
+- The `radius` prop specifies the corner roundness (can be set individually); internally observes the element size (ResizeObserver) to generate the accurate SVG `clip-path`.
+- When a `motion` object is passed, it renders as a motion squircle component combined with framer-motion.
+
+## Type Signatures
+
+```typescript
+import type { ElementType, HTMLAttributes } from "react";
+import type { MotionProps } from "motion/react";
+import type { RadiusValue } from "../Theme/Radius.types";
+
+export interface SquircleProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  "color"
+> {
+  as?: ElementType; // element to render (default: "div")
+  radius?: RadiusValue; // corner radius (scale or pixel unit)
+  cornerRadius?: number; // hardcoded corner radius
+  cornerSmoothing?: number; // smoothing degree (default: 0.6)
+  preserveSmoothing?: boolean;
+  motion?: MotionProps; // animation properties
+}
+```
+
+## Example Code
+
+```tsx
+import Squircle from "@/packages/Frameworks/Squircle";
+
+function Card() {
+  return (
+    <Squircle
+      as="section"
+      radius="R24" // UIKit Radius system token
+      style={{ background: "white", padding: 20 }}
+    >
+      <h2>Soft-corner card</h2>
+      <p>Super Ellipse curvature applied.</p>
+    </Squircle>
+  );
+}
+```