@pihanga2/shadcn 0.2.0 → 0.2.1

package/cards/graphin/graphin.types.d.ts

@@ -1,11 +1,213 @@
-import { PiCardDef } from '@pihanga2/core';
+import { default as React } from 'react';
+import { DispatchF, ReduxAction } from '@pihanga2/core';
 import { GraphData, GraphOptions } from '@antv/g6';
 export declare const GRAPHIN_CARD = "graphin";
-export declare const Graphin: <S extends import('@pihanga2/core').ReduxState>(p: import('@pihanga2/core').PiMapProps<GraphinProps, S, {}>) => PiCardDef;
+export declare const Graphin: <S extends import('@pihanga2/core').ReduxState>(p: import('@pihanga2/core').PiMapProps<GraphinProps, S, GraphinEvents>) => import('@pihanga2/core').PiCardDef;
+export declare const GRAPHIN_ACTION: {
+    NODE_HOVERED: string;
+    NODE_HOVER_END: string;
+    NODE_CLICKED: string;
+    NODE_DBL_CLICKED: string;
+    TOOLTIP_OPEN: string;
+    TOOLTIP_CLOSE: string;
+    CONTEXT_MENU_OPEN: string;
+    CONTEXT_MENU_CLOSE: string;
+};
+export declare const onGraphinNodeHovered: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinNodeHoverEnd: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinNodeClicked: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinNodeDblClicked: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinTooltipOpen: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinTooltipClose: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinContextMenuOpen: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+export declare const onGraphinContextMenuClose: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, ReduxAction & {
+    cardID: string;
+} & GraphinNodeEventContext<Record<string, unknown>>>) => void;
+/**
+ * Payload carried by all node interaction events.
+ * Also forwarded as props to tooltip / context-menu `PiCard` content cards
+ * so they can render node-specific information.
+ */
+export type GraphinNodeEventContext<T = Record<string, unknown>> = {
+    /** The G6 node id */
+    nodeId: string;
+    /** The node's `data` bag as stored in `GraphData` */
+    nodeData?: T;
+    /** Canvas x-coordinate of the pointer when the event fired */
+    x: number;
+    /** Canvas y-coordinate of the pointer when the event fired */
+    y: number;
+};
+/**
+ * Convenience union of every built-in G6 layout-type string.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"force-atlas2"` | Force Atlas 2 – general-purpose force (default) |
+ * | `"force"` / `"gforce"` | Classic force-directed |
+ * | `"d3-force"` | D3 force simulation |
+ * | `"fruchterman"` | Fruchterman-Reingold force |
+ * | `"dagre"` | Hierarchical / DAG (Dagre) |
+ * | `"antv-dagre"` | AntV variant of Dagre |
+ * | `"circular"` | Nodes arranged in a circle |
+ * | `"concentric"` | Concentric rings ordered by degree |
+ * | `"radial"` | Radial tree from a focal node |
+ * | `"grid"` | Uniform grid |
+ * | `"mds"` | Multi-dimensional scaling |
+ * | `"random"` | Random positions |
+ * | `"snake"` | Snake / serpentine path |
+ * | `"fishbone"` | Fishbone / Ishikawa diagram |
+ */
+export type GraphinLayoutType = "force-atlas2" | "force" | "gforce" | "d3-force" | "d3-force3d" | "fruchterman" | "fruchterman-gpu" | "dagre" | "antv-dagre" | "circular" | "concentric" | "radial" | "grid" | "mds" | "random" | "snake" | "fishbone";
 export type GraphinProps = {
     data: GraphData;
     options?: Partial<Omit<GraphOptions, "data">>;
+    /**
+     * Shorthand for `options.layout.type`.  When provided it overrides whatever
+     * layout type is set inside `options.layout`, while still preserving any
+     * other layout parameters (e.g. `rankdir`, `preventOverlap`, …) you set
+     * via `options`.
+     *
+     * Pass the full options as `options.layout` when you also need to tweak
+     * layout-specific parameters.
+     *
+     * @default "force-atlas2"
+     */
+    layout?: GraphinLayoutType;
+    /**
+     * When `true` the default `zoom-canvas` behavior is removed, preventing
+     * the user from zooming in/out with the scroll wheel.
+     *
+     * Useful when the graph is embedded inside a scrollable page and you do
+     * not want accidental scroll events to zoom the canvas instead of
+     * scrolling the page.
+     *
+     * You can still customise or re-enable zoom by passing a `zoom-canvas`
+     * entry in `options.behaviors`.
+     *
+     * @default false
+     */
+    suppressZoom?: boolean;
+    /**
+     * When `true` the default `drag-canvas` behavior is removed, preventing
+     * the user from **panning** (moving the entire canvas) by click-dragging
+     * on the background.
+     *
+     * Useful when you want to lock the viewport (e.g. an embedded static
+     * overview) or when touch-scroll conflicts with canvas pan on mobile.
+     *
+     * You can still customise or re-enable panning by passing a `drag-canvas`
+     * entry in `options.behaviors`.
+     *
+     * @default false
+     */
+    suppressPan?: boolean;
+    /**
+     * When `true` the default `drag-element` behavior is removed, preventing
+     * the user from **dragging individual nodes** to rearrange them after the
+     * initial layout has been applied.
+     *
+     * By default nodes are freely repositionable.  Set this to `true` to
+     * produce a read-only graph where the computed layout is preserved exactly.
+     *
+     * You can still customise or re-enable node dragging by passing a
+     * `drag-element` entry in `options.behaviors`.
+     *
+     * @default false
+     */
+    suppressDrag?: boolean;
+    /**
+     * Initial zoom level of the canvas viewport.
+     *
+     * **Range:** `0.02` – `16`  (G6's default `zoomRange`)
+     * - `1` = 100 % (actual size)
+     * - `< 1` zooms out — e.g. `0.5` shows everything at 50 %
+     * - `> 1` zooms in — e.g. `2` shows everything at 200 %
+     *
+     * Setting this prop automatically disables G6's default `autoFit: 'view'`
+     * behaviour (which would otherwise fit the graph to the container and
+     * override the requested zoom level).
+     *
+     * The user can still change the zoom interactively via scroll unless
+     * `suppressZoom` is also set.
+     *
+     * @example 0.5  // 50 % — useful for large graphs; shows the full picture
+     * @example 1    // 100 % — natural size
+     * @example 2    // 200 % — start zoomed in on a small graph
+     */
+    zoomLevel?: number;
+    /**
+     * When `true` every edge is rendered with an arrowhead at its **target**
+     * end, making the graph visually directed.
+     *
+     * You can override arrow style granularly via
+     * `options.edge.style.endArrow` / `options.edge.style.startArrow`.
+     *
+     * @default false
+     */
+    directed?: boolean;
+    /**
+     * Hover tooltip — shown while the pointer is over a node or edge.
+     * The specified `PiCardDef` is rendered inside a floating panel with
+     * `pointerEvents: none`.  The card receives `GraphinNodeEventContext`
+     * as extra props.
+     */
     tooltip?: GraphinTooltip;
+    /**
+     * Context panel — opens when the user clicks a node and stays visible
+     * until they click outside it or press the built-in ✕ close button.
+     * The panel is interactive (`pointerEvents: auto`) and passes an
+     * `onClose` callback as well as `GraphinNodeEventContext` to the card.
+     */
+    contextMenu?: GraphinContextMenu;
+    /**
+     * Serialisable map from **style name** → visual spec used to style nodes
+     * without JavaScript functions in props (required for Redux serialisation).
+     *
+     * Nodes and edges reference a style by setting a string field in their
+     * `data` object.  The field name defaults to `"style"` and can be
+     * overridden with `nodeStyleKey`.
+     *
+     * The component builds the G6 style functions internally from this map, so
+     * the layout engine never re-runs when styles change — use the
+     * `dispatchGraphinUpdateNodeStyleMap` OP to update styles at runtime.
+     *
+     * @example
+     * ```ts
+     * nodeStyles: {
+     *   gateway: { type: "star",   fill: "#e67e22", size: 48, labelFill: "#fff" },
+     *   service: { type: "circle", fill: "#2980b9", size: 32, labelFill: "#fff" },
+     *   db:      { type: "rect",   fill: "#8e44ad", size: 22, labelFill: "#fff" },
+     * }
+     * // node data:
+     * { id: "gw", data: { displayName: "Gateway", style: "gateway" } }
+     * ```
+     */
+    nodeStyles?: GraphinNodeStyleMap;
+    /**
+     * The field name inside `node.data` that holds the style name to look up
+     * in `nodeStyles`.
+     *
+     * Useful when your data already has a different key (e.g. `"role"`,
+     * `"type"`, `"category"`).
+     *
+     * @default "style"
+     */
+    nodeStyleKey?: string;
     style?: {
         root?: React.CSSProperties;
         item?: React.CSSProperties;
@@ -13,6 +215,244 @@ export type GraphinProps = {
     className?: string;
 };
 export type GraphinTooltip = {
-    node?: PiCardDef;
-    edge?: PiCardDef;
+    /** Registered card name whose component is rendered inside the floating panel. */
+    node?: string;
+    edge?: string;
+    /**
+     * Pixel gap between the pointer position and the top-left corner of the
+     * tooltip panel.  Pass a single number for equal x/y offset, or
+     * `[xOffset, yOffset]` to control each axis independently.
+     *
+     * @default 4
+     */
+    offset?: number | [number, number];
+};
+export type GraphinContextMenu = {
+    /** Registered card name whose component is rendered inside the click panel. */
+    node?: string;
+    edge?: string;
+    /**
+     * Pixel gap between the click point and the top-left corner of the context
+     * panel.  Pass a single number for equal x/y offset, or
+     * `[xOffset, yOffset]` to control each axis independently.
+     *
+     * @default 4
+     */
+    offset?: number | [number, number];
+};
+/**
+ * Node shape types supported by G6 v5.
+ */
+export type GraphinNodeShape = "circle" | "rect" | "diamond" | "star" | "triangle" | "hexagon" | "ellipse";
+/**
+ * Serialisable visual specification for a named node style.
+ *
+ * All fields are optional — unset fields fall back to the card's base style.
+ */
+export type GraphinNodeStyleDef = {
+    /** Node shape.  @default "circle" */
+    type?: GraphinNodeShape;
+    /** Fill colour (CSS colour string). */
+    fill?: string;
+    /** Border colour. */
+    stroke?: string;
+    /** Border thickness in pixels. */
+    lineWidth?: number;
+    /**
+     * Node size in pixels.
+     * Pass a number for a square/circle; pass `[width, height]` for a rectangle.
+     */
+    size?: number | [number, number];
+    /** Fill opacity 0–1. */
+    opacity?: number;
+    /** Label text colour. */
+    labelFill?: string;
+    /** Label font size in pixels. */
+    labelFontSize?: number;
+};
+/**
+ * Map from **style name** → visual spec.
+ *
+ * Nodes reference a style by setting a string field in their `data` object
+ * (default field name: `"style"`).  The component looks up that name here
+ * and builds the G6 style functions internally — so no JavaScript functions
+ * ever appear in props (safe for Redux serialisation).
+ *
+ * @example
+ * ```ts
+ * nodeStyles: {
+ *   gateway: { type: "star",   fill: "#e67e22", size: 48 },
+ *   service: { type: "circle", fill: "#2980b9", size: 32 },
+ *   db:      { type: "rect",   fill: "#8e44ad", size: 22 },
+ *   failed:  { fill: "#e74c3c", stroke: "#c0392b", lineWidth: 3 },
+ * }
+ * ```
+ */
+export type GraphinNodeStyleMap = Record<string, GraphinNodeStyleDef>;
+/**
+ * OP actions let external code drive G6 imperatively (highlight nodes,
+ * zoom to a node, etc.) without touching `data` or `options` — so the
+ * layout engine NEVER re-runs.
+ *
+ * Dispatch with the `dispatchGraphin*` helpers exported from this module.
+ */
+export declare const GRAPHIN_OP_ACTION: {
+    SET_NODE_STYLES: string;
+    CLEAR_NODE_STYLES: string;
+    ZOOM_TO_NODE: string;
+    UPDATE_NODE_STYLE_MAP: string;
+};
+/**
+ * Payload for `GRAPHIN_OP_ACTION.SET_NODE_STYLES`.
+ *
+ * Sets the style-name field (determined by `nodeStyleKey`, default `"style"`)
+ * on each specified node, then calls `graph.draw()` so the new style name is
+ * looked up in `nodeStyles` and applied visually — **zero layout re-runs**.
+ *
+ * @example
+ * ```ts
+ * // Mark two nodes as failed; they will immediately render with the "failed"
+ * // visual spec from the nodeStyles map.
+ * dispatchGraphinSetNodeStyles(dispatch, {
+ *   cardName: "myGraph",
+ *   nodeStyles: { "db-u": "failed", "users": "degraded" },
+ * });
+ * ```
+ */
+export type GraphinSetNodeStylesAction = {
+    cardName: string;
+    /**
+     * Map of `nodeId` → style name (must be a key in the card's `nodeStyles` map).
+     * @example { n1: "failed", n2: "degraded", n3: "ok" }
+     */
+    nodeStyles: Record<string, string>;
+};
+/**
+ * Payload for `GRAPHIN_OP_ACTION.CLEAR_NODE_STYLES`.
+ *
+ * Removes the style-name field from the specified nodes (or all nodes when
+ * `nodeIds` is omitted), reverting them to the default `nodeStyles` fallback
+ * appearance.  Calls `graph.draw()` — **zero layout re-runs**.
+ *
+ * @example
+ * ```ts
+ * // Restore all nodes to their default style
+ * dispatchGraphinClearNodeStyles(dispatch, { cardName: "myGraph" });
+ * ```
+ */
+export type GraphinClearNodeStylesAction = {
+    cardName: string;
+    /** Nodes to clear — omit to clear ALL nodes in the graph. */
+    nodeIds?: string[];
+};
+/**
+ * Payload for `GRAPHIN_OP_ACTION.ZOOM_TO_NODE`.
+ *
+ * Pans (and optionally zooms) the viewport so the target node is centred.
+ */
+export type GraphinZoomToNodeAction = {
+    cardName: string;
+    nodeId: string;
+    /** Desired zoom level after centering.  Omit to keep the current zoom. */
+    zoomLevel?: number;
+    /** Animation duration in milliseconds.  @default 400 */
+    duration?: number;
+};
+/**
+ * Set the style name on individual nodes — zero layout re-runs.
+ *
+ * The style name is written to the `nodeStyleKey` field in each node's data
+ * bag, then `graph.draw()` is called so the `nodeStyles` map is re-evaluated
+ * and the new colour / shape / size appears immediately.
+ *
+ * @example
+ * ```ts
+ * dispatchGraphinSetNodeStyles(dispatch, {
+ *   cardName: "myGraph",
+ *   nodeStyles: { "db-u": "failed", "users": "degraded" },
+ * });
+ * ```
+ */
+export declare const dispatchGraphinSetNodeStyles: (dispatch: DispatchF, payload: GraphinSetNodeStylesAction) => string;
+/**
+ * Clear the style name from nodes (all nodes when `nodeIds` is omitted).
+ * Nodes revert to the default fallback appearance defined in the component.
+ *
+ * @example
+ * ```ts
+ * dispatchGraphinClearNodeStyles(dispatch, { cardName: "myGraph" });
+ * ```
+ */
+export declare const dispatchGraphinClearNodeStyles: (dispatch: DispatchF, payload: GraphinClearNodeStylesAction) => string;
+/**
+ * Pan (and optionally zoom) the viewport to centre a node.
+ *
+ * @example
+ * ```ts
+ * dispatchGraphinZoomToNode(dispatch, {
+ *   cardName: "myGraph",
+ *   nodeId:   "n3",
+ *   zoomLevel: 1.5,
+ *   duration:  600,
+ * });
+ * ```
+ */
+export declare const dispatchGraphinZoomToNode: (dispatch: DispatchF, payload: GraphinZoomToNodeAction) => string;
+/**
+ * Payload for `GRAPHIN_OP_ACTION.UPDATE_NODE_STYLE_MAP`.
+ *
+ * Merges (or replaces) style definitions in the card's live style map and
+ * triggers a G6 re-draw — **without** re-running the layout engine.
+ *
+ * Use this to animate node colours, highlight failures, show traffic
+ * intensity, etc. at runtime.
+ */
+export type GraphinUpdateNodeStyleMapAction = {
+    cardName: string;
+    /**
+     * Style definitions to merge into the current map.
+     * @example { failed: { fill: "#e74c3c", stroke: "#c0392b" } }
+     */
+    styles: GraphinNodeStyleMap;
+    /**
+     * When `true`, replaces the entire map instead of merging.
+     * @default false
+     */
+    replace?: boolean;
+};
+/**
+ * Merge new style definitions into the card's live node style map and
+ * trigger a re-draw — zero layout re-runs.
+ *
+ * The style map is kept in a React ref inside the component so updates are
+ * applied immediately without going through Redux state.
+ *
+ * @example
+ * ```ts
+ * // Mark "users" node style as failed (red) without touching node data
+ * dispatchGraphinUpdateNodeStyleMap(dispatch, {
+ *   cardName: "myGraph",
+ *   styles: { service: { fill: "#e74c3c", stroke: "#c0392b" } },
+ * });
+ * ```
+ */
+export declare const dispatchGraphinUpdateNodeStyleMap: (dispatch: DispatchF, payload: GraphinUpdateNodeStyleMapAction) => string;
+export type { ReduxAction };
+export type GraphinEvents = {
+    /** Fired when the pointer enters a node */
+    onNodeHovered: GraphinNodeEventContext;
+    /** Fired when the pointer leaves a node */
+    onNodeHoverEnd: GraphinNodeEventContext;
+    /** Fired on a single click on a node */
+    onNodeClicked: GraphinNodeEventContext;
+    /** Fired on a double-click on a node */
+    onNodeDblClicked: GraphinNodeEventContext;
+    /** Fired when the hover tooltip becomes visible */
+    onTooltipOpen: GraphinNodeEventContext;
+    /** Fired when the hover tooltip is dismissed */
+    onTooltipClose: GraphinNodeEventContext;
+    /** Fired when the context-menu panel opens */
+    onContextMenuOpen: GraphinNodeEventContext;
+    /** Fired when the context-menu panel closes */
+    onContextMenuClose: GraphinNodeEventContext;
 };

package/cards/graphin/graphinOpHandler.component.d.ts

@@ -0,0 +1,8 @@
+import { GraphinNodeStyleMap } from './graphin.types';
+export type GraphinOpHandlerProps = {
+    cardName: string;
+    nodeStylesRef: React.MutableRefObject<GraphinNodeStyleMap>;
+    /** Ref to the current nodeStyleKey (defaults to "style"). */
+    nodeStyleKeyRef: React.MutableRefObject<string>;
+};
+export declare function GraphinOpHandler({ cardName, nodeStylesRef, nodeStyleKeyRef, }: GraphinOpHandlerProps): null;

package/cards/graphin/index.d.ts

@@ -1,2 +1,3 @@
 export * from './graphin.types';
 export type { TooltipContext } from './tooltip.component';
+export type { ContextMenuContext } from './contextMenu.component';

package/cards/graphin/tooltip.component.d.ts

@@ -1,10 +1,22 @@
-import { GraphinTooltip } from './graphin.types';
+import { GraphinNodeEventContext, GraphinTooltip } from './graphin.types';
+/**
+ * Context forwarded to the tooltip content card as props.
+ *
+ * ```ts
+ * type MyTooltipProps = TooltipContext & { ... }
+ * ```
+ */
 export type TooltipContext<T = Record<string, unknown>> = {
+    /** `true` when the hovered element is an edge, `false` for a node */
     isEdge?: boolean;
+    /** The G6 element id */
     elementID?: string;
+    /** The element's raw `data` bag */
     elementData?: T;
 };
 export declare function TooltipComponent(props: {
     contentCards: GraphinTooltip;
     parentCard: string;
+    onOpen?: (ctx: GraphinNodeEventContext) => void;
+    onClose?: (ctx: GraphinNodeEventContext) => void;
 }): React.ReactNode;

package/cards/slider/index.d.ts

@@ -0,0 +1 @@
+export * from './slider.types';

package/cards/slider/slider.component.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { PiCardProps } from '@pihanga2/core';
+import { PiSliderEvents, PiSliderProps } from './slider.types';
+export declare const SliderComponent: (props: PiCardProps<PiSliderProps, PiSliderEvents>) => React.ReactNode;

package/cards/slider/slider.types.d.ts

@@ -0,0 +1,102 @@
+export declare const PI_SLIDER_CARD = "shad/slider";
+export declare const Slider: <S extends import('@pihanga2/core').ReduxState>(p: import('@pihanga2/core').PiMapProps<PiSliderProps, S, PiSliderEvents>) => import('@pihanga2/core').PiCardDef;
+export declare const PI_SLIDER_ACTION: {
+    CHANGED: string;
+    COMMITTED: string;
+};
+export declare const onPiSliderChanged: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, import('@pihanga2/core').ReduxAction & {
+    cardID: string;
+} & PiSliderChangedEvent>) => void;
+/**
+ * Fired once when the user **finishes** dragging (mouse-up / touch-end).
+ *
+ * Use this instead of `onPiSliderChanged` when you only care about the final
+ * settled value and do not want to process every intermediate drag position.
+ */
+export declare const onPiSliderCommitted: <S extends import('@pihanga2/core').ReduxState>(register: import('@pihanga2/core').PiRegister, f: import('@pihanga2/core').ReduceF<S, import('@pihanga2/core').ReduxAction & {
+    cardID: string;
+} & PiSliderCommittedEvent>) => void;
+export type PiSliderProps = {
+    /**
+     * Field name used to bind to FormContext when inside a pi/form card.
+     * When provided the component reads its value from form data and writes
+     * back via form.handleChange.
+     */
+    name?: string;
+    /**
+     * Controlled numeric value (single thumb).
+     * Ignored when `name` is set and the component is inside a pi/form,
+     * and also ignored when `selfManaged` is true (use `defaultValue` instead).
+     */
+    value?: number;
+    /**
+     * Initial value used when `selfManaged` is true.
+     * Falls back to `value` → `min` → 0 if not provided.
+     */
+    defaultValue?: number;
+    /**
+     * When true the slider keeps its own internal value state.
+     * Dragging updates the displayed value immediately without needing an
+     * external state update.  `onChanged` is still fired on every change so
+     * the app can react (or log) without being responsible for feeding the
+     * value back as a prop.
+     *
+     * Ignored when inside a pi/form (form state takes precedence).
+     */
+    selfManaged?: boolean;
+    /** Minimum value of the slider range. Defaults to 0. */
+    min?: number;
+    /** Maximum value of the slider range. Defaults to 100. */
+    max?: number;
+    /** Stepping interval between selectable values. Defaults to 1. */
+    step?: number;
+    /** When true, the slider is disabled and non-interactive. */
+    disabled?: boolean;
+    /**
+     * Debounce delay in milliseconds applied to `onChanged` during continuous
+     * drag.  Only the last value within each quiet window is dispatched.
+     *
+     * Useful when the `onChanged` handler is expensive (e.g. triggers an API
+     * call) — set e.g. `debounceMs: 200` to cap the event rate.
+     *
+     * Has no effect on `onCommitted`, which always fires exactly once at
+     * drag-end regardless of this setting.
+     *
+     * Omit (or set to 0) to dispatch on every drag position (default behaviour).
+     */
+    debounceMs?: number;
+    /**
+     * When true, `onPiSliderChanged` is **never** dispatched during drag.
+     *
+     * Use this together with `onPiSliderCommitted` when you only care about
+     * the final settled value and want to eliminate all intermediate Redux
+     * actions entirely (stricter than `debounceMs`).
+     *
+     * `onPiSliderCommitted` is unaffected and always fires on release.
+     * `selfManaged` visual updates are also unaffected.
+     */
+    suppressChangedEvents?: boolean;
+    /**
+     * Optional label text rendered above the slider.
+     * When provided, the current numeric value is shown to the right of the label.
+     */
+    label?: string;
+    /** Extra Tailwind / CSS classes forwarded to the root wrapper element. */
+    className?: string;
+};
+export type PiSliderChangedEvent = {
+    /** Field name, mirrors the `name` prop if provided. */
+    name?: string;
+    /** New numeric value after the change. */
+    value: number;
+};
+export type PiSliderCommittedEvent = {
+    /** Field name, mirrors the `name` prop if provided. */
+    name?: string;
+    /** Final settled value when the user released the thumb. */
+    value: number;
+};
+export type PiSliderEvents = {
+    onChanged: PiSliderChangedEvent;
+    onCommitted: PiSliderCommittedEvent;
+};

package/cards/sliderValue/index.d.ts

@@ -0,0 +1 @@
+export * from './sliderValue.types';

package/cards/sliderValue/sliderValue.component.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { PiCardProps } from '@pihanga2/core';
+import { PiSliderValueProps } from './sliderValue.types';
+/**
+ * Display-only companion to `shad/slider`.
+ *
+ * Renders the same track + filled-range visual as the interactive slider but
+ * with no thumb and no user interaction.  Use this card to show a read-only
+ * numeric value in contexts where editing is not permitted (e.g. a summary
+ * panel, a table cell, or a loading state).
+ *
+ * The component uses the same Tailwind classes as `src/components/ui/slider.tsx`
+ * so the two cards look identical.
+ */
+export declare const SliderValueComponent: (props: PiCardProps<PiSliderValueProps>) => React.ReactNode;

package/cards/sliderValue/sliderValue.types.d.ts

@@ -0,0 +1,21 @@
+export declare const PI_SLIDER_VALUE_CARD = "shad/slider-value";
+export declare const SliderValue: <S extends import('@pihanga2/core').ReduxState>(p: import('@pihanga2/core').PiMapProps<PiSliderValueProps, S, {}>) => import('@pihanga2/core').PiCardDef;
+export type PiSliderValueProps = {
+    /**
+     * The numeric value to display on the track.
+     * Clamped between `min` and `max`.
+     */
+    value: number;
+    /** Minimum value of the range. Defaults to 0. */
+    min?: number;
+    /** Maximum value of the range. Defaults to 100. */
+    max?: number;
+    /**
+     * Optional label text rendered above the track.
+     * When provided, the numeric value is shown to the right of the label,
+     * matching the interactive `shad/slider` layout exactly.
+     */
+    label?: string;
+    /** Extra Tailwind / CSS classes forwarded to the root wrapper element. */
+    className?: string;
+};