@altruist03/ui 0.0.0-stage → 0.2.0

package/src/components/Selector/Selector.types.ts

@@ -0,0 +1,71 @@
+import React from 'react';
+
+export type SelectorOption = string | { label?: string; [key: string]: unknown };
+
+// ----- Unified props: multiple=false => value T|null, multiple=true => value T[] -----
+export interface SelectorProps<T extends SelectorOption> {
+  /** When true, multi-select with checkboxes and chips; when false, single select. */
+  multiple?: boolean;
+  options: T[];
+  /** Single: T | null. Multiple: T[]. */
+  value: T | null | T[];
+  /** Single: (value: T | null) => void. Multiple: (value: T[]) => void. */
+  onChange?: (value: T | null | T[]) => void;
+  label?: string;
+  placeholder?: string;
+  required?: boolean;
+  error?: boolean | string;
+  helperText?: string;
+  disabled?: boolean;
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  /** Background color variant */
+  color?: 'grey' | 'white';
+  noOptionsText?: string;
+  loading?: boolean;
+  loadingText?: string;
+  isOptionDisabled?: (option: T) => boolean;
+  getOptionLabel?: (option: T) => string;
+  renderOption?: (option: T, state: { index: number }) => React.ReactNode;
+  /**
+   * Group options by a string key (similar to MUI Autocomplete `groupBy`).
+   * When provided, the listbox will render grouped sections.
+   */
+  groupBy?: (option: T) => string;
+  /**
+   * Custom group renderer (similar to MUI Autocomplete `renderGroup`).
+   * Called only when `groupBy` is provided.
+   * The heading div with background is always rendered by Selector; return only the list content (e.g. ul with children).
+   */
+  renderGroup?: (params: {
+    key: string;
+    group: string;
+    children: React.ReactNode;
+  }) => React.ReactNode;
+  id?: string;
+  /** Only when multiple: max chips shown before "+N". -1 = no limit. */
+  limitTags?: number;
+  /** Show clear button on hover/select. Default true. */
+  clearable?: boolean;
+  filterOptions?: (
+    options: T[],
+    state: { inputValue: string; getOptionLabel: (option: T) => string }
+  ) => T[];
+  /** Handler for scroll events on the listbox */
+  onListboxScroll?: (event: React.UIEvent<HTMLUListElement>) => void;
+  /** Called when the dropdown opens or closes */
+  onOpenChange?: (open: boolean) => void;
+  /** Optional external trigger for opening/closing the dropdown. */
+  open?: boolean;
+  /** Loading state - shows skeleton instead of component */
+  skeletonLoading?: boolean;
+  onInput?: React.FormEventHandler<HTMLInputElement>;
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+  /** When true, render country flag (from option.iso) before each option label. */
+  showFlag?: boolean;
+  /** Browser autocomplete hint for the underlying input. */
+  autoComplete?: string;
+  /** Minimum width (px) for the dropdown listbox. */
+  listboxMinWidth?: number;
+  /** Custom equality check between an option and a selected value. Defaults to reference equality. */
+  isOptionEqualToValue?: (option: T, value: T) => boolean;
+}

package/src/components/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Skeleton } from "./Skeleton";
+
+const meta: Meta<typeof Skeleton> = {
+  title: "Design System/Skeleton",
+  component: Skeleton,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: "24px", width: "520px", maxWidth: "100%" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    height: 20,
+    width: "100%",
+    borderRadius: 8,
+    enableAnimation: true,
+  },
+  argTypes: {
+    count: {
+      control: { type: "number", min: 1 },
+      description: "Number of skeleton placeholders to render",
+      table: { type: { summary: "number" } },
+    },
+    height: {
+      control: { type: "number" },
+      description: "Height (px when number)",
+      table: { type: { summary: "string | number" } },
+    },
+    width: {
+      control: { type: "text" },
+      description: "Width (number or CSS string)",
+      table: { type: { summary: "string | number" } },
+    },
+    borderRadius: {
+      control: { type: "text" },
+      description: "Border radius (number or CSS string)",
+      table: { type: { summary: "string | number" } },
+    },
+    circle: {
+      control: { type: "boolean" },
+      description: "Render as a circle (useful for avatars)",
+      table: { type: { summary: "boolean" } },
+    },
+    enableAnimation: {
+      control: { type: "boolean" },
+      description: "Enable/disable shimmer animation",
+      table: { type: { summary: "boolean" } },
+    },
+    duration: {
+      control: { type: "number", min: 0 },
+      description: "Animation duration (seconds)",
+      table: { type: { summary: "number" } },
+    },
+    direction: {
+      control: { type: "radio" },
+      options: ["ltr", "rtl"],
+      description: "Animation direction",
+      table: { type: { summary: '"ltr" | "rtl"' } },
+    },
+    inline: {
+      control: { type: "boolean" },
+      description: "Render inline (useful alongside text)",
+      table: { type: { summary: "boolean" } },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Skeleton>;
+
+export const Playground: Story = {
+  args: {},
+};
+
+const ShowcaseComponent = () => {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+      {/* Card-sized block (matches dashboard usage) */}
+      <div>
+        <div style={{ fontSize: "12px", marginBottom: "8px" }}>
+          Card placeholder
+        </div>
+        <Skeleton height={108} borderRadius={16} />
+      </div>
+
+      {/* Text lines */}
+      <div>
+        <div style={{ fontSize: "12px", marginBottom: "8px" }}>Text lines</div>
+        <Skeleton height={14} width="100%" style={{ marginBottom: 8 }} />
+        <Skeleton height={14} width="92%" style={{ marginBottom: 8 }} />
+        <Skeleton height={14} width="76%" />
+      </div>
+
+      {/* Avatar + text row */}
+      <div>
+        <div style={{ fontSize: "12px", marginBottom: "8px" }}>
+          Avatar + text
+        </div>
+        <div style={{ display: "flex", alignItems: "center", gap: "12px" }}>
+          <Skeleton circle width={44} height={44} />
+          <div style={{ flex: 1 }}>
+            <Skeleton height={14} width="60%" style={{ marginBottom: 8 }} />
+            <Skeleton height={12} width="40%" />
+          </div>
+        </div>
+      </div>
+
+      {/* Multiple items */}
+      <div>
+        <div style={{ fontSize: "12px", marginBottom: "8px" }}>
+          Multiple items
+        </div>
+        <Skeleton count={4} height={12} style={{ marginBottom: 8 }} />
+      </div>
+
+      {/* No animation */}
+      <div>
+        <div style={{ fontSize: "12px", marginBottom: "8px" }}>
+          No animation
+        </div>
+        <Skeleton height={40} enableAnimation={false} />
+      </div>
+    </div>
+  );
+};
+
+export const Showcase: Story = {
+  render: () => <ShowcaseComponent />,
+};

package/src/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,20 @@
+import PluginSkeleton from 'react-loading-skeleton';
+import 'react-loading-skeleton/dist/skeleton.css';
+
+import { useTokens } from '../../ThemeProvider/ThemeContext';
+import { getSkeletonTokensFromResolved } from '../../tokens';
+import type { SkeletonProps } from './Skeleton.types';
+
+/**
+ * Design-system Skeleton component. Wraps react-loading-skeleton and applies
+ * design tokens for baseColor and highlightColor by default. All props are
+ * passed through to the plugin; component props override token defaults.
+ */
+export const Skeleton = (props: SkeletonProps) => {
+  const resolvedTokens = useTokens();
+  const tokens = getSkeletonTokensFromResolved(resolvedTokens);
+
+  const { baseColor = tokens.baseColor, highlightColor = tokens.highlightColor, ...rest } = props;
+
+  return <PluginSkeleton baseColor={baseColor} highlightColor={highlightColor} {...rest} />;
+};

package/src/components/Skeleton/Skeleton.types.ts

@@ -0,0 +1,3 @@
+export type SkeletonProps = import("react-loading-skeleton").SkeletonProps;
+export type SkeletonStyleProps =
+  import("react-loading-skeleton").SkeletonStyleProps;

package/src/components/Spinner/Spinner.stories.tsx

@@ -0,0 +1,84 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Spinner } from "./Spinner";
+import type { SpinnerProps } from "./Spinner.types";
+
+const meta: Meta<typeof Spinner> = {
+  title: "Design System/Spinner",
+  component: Spinner,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: "24px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    size: undefined,
+    color: "currentColor",
+  } as SpinnerProps,
+  argTypes: {
+    size: {
+      control: "text",
+      description: "Size of the spinner (e.g., '24px', '2rem', 24)",
+    },
+    color: {
+      control: "color",
+      description: "Color of the spinner. Defaults to 'currentColor'.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Spinner>;
+
+export const Playground: Story = {
+  args: {
+    size: 24,
+    color: "#ff5722",
+  },
+  render: (args) => <Spinner {...args} />,
+};
+
+const ShowcaseComponent = () => {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px", color: "#333" }}>
+      <div>
+        <h4 style={{ margin: "0 0 8px 0", fontSize: "14px", fontWeight: 600 }}>Default</h4>
+        <Spinner />
+      </div>
+
+      <div>
+        <h4 style={{ margin: "0 0 8px 0", fontSize: "14px", fontWeight: 600 }}>Custom Size</h4>
+        <div style={{ display: "flex", gap: "16px", alignItems: "center" }}>
+          <Spinner size={16} />
+          <Spinner size={32} />
+          <Spinner size={48} />
+        </div>
+      </div>
+
+      <div>
+        <h4 style={{ margin: "0 0 8px 0", fontSize: "14px", fontWeight: 600 }}>Custom Color</h4>
+        <div style={{ display: "flex", gap: "16px", alignItems: "center" }}>
+          <Spinner color="#f44336" />
+          <Spinner color="#4caf50" />
+          <Spinner color="#2196f3" />
+        </div>
+      </div>
+
+      <div>
+        <h4 style={{ margin: "0 0 8px 0", fontSize: "14px", fontWeight: 600 }}>Inherited Color</h4>
+        <div style={{ color: "#9c27b0", display: "flex", alignItems: "center", gap: "8px" }}>
+          <span>Parent text color is purple</span>
+          <Spinner />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const Showcase: Story = {
+  render: () => <ShowcaseComponent />,
+};

package/src/components/Spinner/Spinner.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useRef } from "react";
+import { useTokens } from "../../ThemeProvider/ThemeContext";
+import { getButtonTokensFromResolved } from "../../tokens";
+import type { SpinnerProps } from "./Spinner.types";
+
+const KEYFRAMES_ID = "ds-spinner-keyframes";
+
+function ensureKeyframes() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(KEYFRAMES_ID)) return;
+
+  const css = `
+@keyframes dsSpinnerSpin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}`;
+
+  const style = document.createElement("style");
+  style.id = KEYFRAMES_ID;
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+export const Spinner = ({
+  size,
+  color = "currentColor",
+  style,
+}: SpinnerProps) => {
+  const resolvedTokens = useTokens();
+  const { sizes } = getButtonTokensFromResolved(resolvedTokens);
+
+  // Default to md button icon size
+  const defaultSize = sizes.md.fontSize;
+  const finalSize = size ?? defaultSize;
+
+  const injectedRef = useRef(false);
+
+  useEffect(() => {
+    if (!injectedRef.current) {
+      ensureKeyframes();
+      injectedRef.current = true;
+    }
+  }, []);
+
+  return (
+    <svg
+      width={finalSize}
+      height={finalSize}
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      style={{
+        animation: "dsSpinnerSpin 1s linear infinite",
+        display: "block",
+        transformOrigin: "center",
+        ...style,
+        fill: "transparent",
+      }}
+    >
+      <circle
+        cx="12"
+        cy="12"
+        r="10"
+        stroke={color}
+        strokeOpacity="0.25"
+        strokeWidth="3"
+      />
+      <circle
+        cx="12"
+        cy="12"
+        r="10"
+        stroke={color}
+        strokeWidth="3"
+        strokeLinecap="round"
+        strokeDasharray="20 60"
+      />
+    </svg>
+  );
+};

package/src/components/Spinner/Spinner.types.ts

@@ -0,0 +1,8 @@
+export interface SpinnerProps {
+  /** Size of the spinner, typically inheriting the font size */
+  size?: number | string;
+  /** Color of the spinner, inherits current color by default */
+  color?: string;
+  /** Additional styles for the SVG element */
+  style?: React.CSSProperties;
+}

package/src/components/StatCard/StatCard.stories.tsx

@@ -0,0 +1,125 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { StatCard } from './StatCard';
+import type { StatCardProps } from './StatCard.types';
+
+function CheckIcon() {
+  return (
+    <svg
+      width={14}
+      height={14}
+      viewBox="0 0 14 14"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden
+    >
+      <path
+        d="M2.5 7L5.5 10L11.5 4"
+        stroke="currentColor"
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function AlertIcon() {
+  return (
+    <svg width={14} height={14} viewBox="0 0 14 14" fill="none" aria-hidden>
+      <path d="M7 3.5V8" stroke="currentColor" strokeWidth={2} strokeLinecap="round" />
+      <circle cx="7" cy="10.5" r="1" fill="currentColor" />
+    </svg>
+  );
+}
+
+const meta: Meta<typeof StatCard> = {
+  title: 'Design System/StatCard',
+  component: StatCard,
+  tags: [],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 24, maxWidth: 420, backgroundColor: '#E5E9EB' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    label: 'Active',
+    infoNote: 'Rider is currently active and available for assignments',
+    value: '972',
+    accentColor: '#22C55E',
+    iconBackgroundColor: '#DDF3E3',
+    icon: <CheckIcon />,
+  } satisfies StatCardProps,
+  argTypes: {
+    label: { control: { type: 'text' } },
+    infoNote: { control: { type: 'text' } },
+    value: { control: { type: 'text' } },
+    accentColor: { control: { type: 'color' } },
+    iconBackgroundColor: { control: { type: 'color' } },
+    ariaLabel: { control: { type: 'text' } },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof StatCard>;
+
+export const Playground: Story = {
+  args: {
+    label: 'Active',
+    infoNote: 'Rider is currently active and available for assignments',
+    value: '972',
+    accentColor: '#22C55E',
+    iconBackgroundColor: '#DDF3E3',
+    icon: <CheckIcon />,
+  },
+};
+
+export const Showcase: Story = {
+  render: () => (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 16,
+        maxWidth: 400,
+      }}
+    >
+      <StatCard
+        label="Active"
+        infoNote="Rider is currently active and available for assignments"
+        value="972"
+        accentColor="#22C55E"
+        iconBackgroundColor="#DDF3E3"
+        icon={<CheckIcon />}
+      />
+      <StatCard
+        label="Pending"
+        infoNote="Riders waiting for the next approval step"
+        value="14"
+        accentColor="#F97316"
+        iconBackgroundColor="#FFE7D6"
+        icon={<AlertIcon />}
+      />
+      <StatCard
+        label="Completed deliveries"
+        infoNote="Total number of successfully completed delivery orders"
+        value={12840}
+        accentColor="#16A34A"
+        iconBackgroundColor="#DDF3E3"
+        icon={<CheckIcon />}
+        ariaLabel="Completed deliveries: 12840"
+      />
+      <StatCard
+        label="At risk"
+        infoNote="Riders requiring immediate review or intervention"
+        value="3"
+        accentColor="#DC2626"
+        iconBackgroundColor="#FBDCDC"
+        icon={<AlertIcon />}
+      />
+    </div>
+  ),
+};

package/src/components/StatCard/StatCard.tsx

@@ -0,0 +1,167 @@
+import type { CSSProperties } from 'react';
+import { useTokens } from '../../ThemeProvider/ThemeContext';
+import { getStatCardTokensFromResolved } from '../../tokens';
+import type { StatCardProps } from './StatCard.types';
+
+function InfoIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden
+    >
+      <circle cx="6" cy="6" r="5.25" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M6 5.2V8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      <circle cx="6" cy="3.55" r="0.75" fill="currentColor" />
+    </svg>
+  );
+}
+
+function defaultAriaLabel(
+  label: StatCardProps['label'],
+  value: StatCardProps['value'],
+  infoNote?: string
+) {
+  if (typeof label === 'string' || typeof label === 'number') {
+    if (typeof value === 'string' || typeof value === 'number') {
+      return infoNote ? `${label}: ${value}. ${infoNote}` : `${label}: ${value}`;
+    }
+  }
+  return undefined;
+}
+
+export const StatCard = ({
+  label,
+  infoNote,
+  value,
+  accentColor,
+  iconBackgroundColor,
+  icon,
+  ariaLabel,
+  className,
+  style,
+}: StatCardProps) => {
+  const resolvedTokens = useTokens();
+  const t = getStatCardTokensFromResolved(resolvedTokens);
+
+  const mixPercent = `${t.iconWellAccentMixPercent}%`;
+  const iconWellStyle = {
+    ['--stat-accent' as string]: accentColor,
+    ['--stat-well-base' as string]: t.surfaceBackground,
+    width: t.iconWellSize,
+    height: t.iconWellSize,
+    borderRadius: t.iconWellBorderRadius,
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginLeft: '-2px',
+    background:
+      iconBackgroundColor ??
+      `color-mix(in srgb, var(--stat-accent) ${mixPercent}, var(--stat-well-base))`,
+  } as CSSProperties;
+
+  const computedAria = ariaLabel ?? defaultAriaLabel(label, value, infoNote);
+
+  return (
+    <div
+      className={className}
+      role="group"
+      aria-label={computedAria}
+      style={{
+        boxSizing: 'border-box',
+        display: 'flex',
+        flexDirection: 'row',
+        alignItems: 'center',
+        gap: t.gap,
+        padding: t.padding,
+        backgroundColor: t.surfaceBackground,
+        border: t.border,
+        borderRadius: t.borderRadius,
+        ...style,
+      }}
+    >
+      <div style={iconWellStyle}>
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: accentColor,
+            lineHeight: 0,
+          }}
+        >
+          {icon}
+        </div>
+      </div>
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          flex: 1,
+          alignItems: 'flex-start',
+          justifyContent: 'center',
+          minWidth: 0,
+          fontFamily: resolvedTokens.semantic?.typography?.body?.medium?.fontFamily,
+        }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '4px',
+            width: '100%',
+            minWidth: 0,
+          }}
+        >
+          <span
+            style={{
+              flex: 1,
+              fontSize: t.labelFontSize,
+              fontWeight: t.labelFontWeight,
+              color: t.labelColor,
+              lineHeight: 1.2,
+              whiteSpace: 'nowrap',
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+            }}
+          >
+            {label}
+          </span>
+          {infoNote ?
+            <span
+              title={infoNote}
+              aria-label={infoNote}
+              tabIndex={0}
+              style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                color: t.labelColor,
+                opacity: 0.72,
+                cursor: 'pointer',
+                flexShrink: 0,
+                lineHeight: 0,
+              }}
+            >
+              <InfoIcon />
+            </span>
+          : null}
+        </div>
+        <span
+          style={{
+            fontSize: t.valueFontSize,
+            fontWeight: t.valueFontWeight,
+            color: t.valueColor,
+            lineHeight: 1.2,
+          }}
+        >
+          {value}
+        </span>
+      </div>
+    </div>
+  );
+};