@altruist03/ui 0.0.0-stage → 0.2.0

package/src/components/SelectScroll/SelectScroll.types.ts

@@ -0,0 +1,60 @@
+import React from 'react';
+
+export type SelectScrollOption = string | { label?: string; [key: string]: unknown };
+
+export interface SelectScrollProps<T = SelectScrollOption> {
+  placeholder?: string;
+  options?: T[];
+  isDisabled?: boolean;
+  onChange?: (value: T | null) => void;
+  value?: T | null;
+  required?: boolean;
+  isOptionDisabled?: (option: T) => boolean;
+  loading?: boolean;
+  onScroll?: (e: React.UIEvent<HTMLUListElement>) => void;
+  /** Called when list is scrolled near bottom (e.g. to load next page). Pass your API/loadMore function from parent. */
+  onLoadMore?: () => void;
+  /** API method to load more: (pageNum, append) => void. Use with loadMorePage, onLoadMorePageChange, loadMoreHasMore. */
+  loadMoreMethod?: (pageNum: number, append: boolean) => void;
+  /** Current page when using loadMoreMethod (parent state). */
+  loadMorePage?: number;
+  /** Callback when page changes (e.g. setPage from parent). */
+  onLoadMorePageChange?: (nextPage: number) => void;
+  /** Whether more data is available when using loadMoreMethod. */
+  loadMoreHasMore?: boolean;
+  label?: string;
+  size?: 'sm' | 'md' | 'lg';
+  getOptionLabel?: (option: T) => string;
+  isInvalid?: boolean;
+  error?: string;
+  /** Shown below input when not in error state (when isInvalid is false). */
+  helperText?: string;
+  renderOption?: (option: T, state: { index: number }) => React.ReactNode;
+  onInputChange?: (value: string) => void;
+  customRenderOptionView?: (option: T) => React.ReactNode;
+  onBlur?: (e: React.FocusEvent) => void;
+  id?: string;
+  noOptionsText?: string;
+  loadingText?: string;
+  style?: React.CSSProperties;
+  /** Custom filter: (options, { inputValue, getOptionLabel }) => filtered options. When not provided, filters by input matching option label. */
+  filterOptions?: (
+    options: T[],
+    state: { inputValue: string; getOptionLabel: (option: T) => string }
+  ) => T[];
+  /**
+   * When true (default), options are server-driven: no client-side label filtering.
+   * Use `onApiSearch` for debounced backend search.
+   */
+  isApiSearch?: boolean;
+  /** Debounce (ms) before `onApiSearch`. Default 1000. */
+  apiSearchDebounceMs?: number;
+  /** Called after debounce with trimmed search when `isApiSearch` is true. */
+  onApiSearch?: (searchTerm: string) => void;
+  /** Fires when the dropdown opens or closes (not on initial mount). */
+  onOpenChange?: (open: boolean) => void;
+  /** Shows clear (X) action and allows clearing when true. */
+  clearable?: boolean;
+  /** Custom equality for highlighting the selected option. Defaults to matching `value`/`id`, then label. */
+  isOptionEqual?: (option: T, value: T) => boolean;
+}

package/src/components/Selector/Selector.stories.tsx

@@ -0,0 +1,382 @@
+import React, { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Selector from "./Selector";
+import type { SelectorProps, SelectorOption } from "./Selector.types";
+
+// Sample options
+const countryOptions = [
+  "India",
+  "Afghanistan",
+  "UAE",
+  "Albania",
+  "Algeria",
+  "Andorra",
+  "Antigua and Barbuda",
+  "Argentina",
+  "Armenia",
+  "Australia",
+  "Austria",
+  "Bahrain",
+];
+
+const usernameOptions = [
+  "John Doe",
+  "Jane Smith",
+  "Jim Beam",
+  "Jill Johnson",
+  "Jack Johnson",
+];
+
+// Options with objects
+const countryObjectOptions = [
+  { label: "India", code: "in" },
+  { label: "Afghanistan", code: "af" },
+  { label: "UAE", code: "ae" },
+  { label: "Albania", code: "al" },
+  { label: "Algeria", code: "dz" },
+];
+
+type RegionCountryOption = { label: string; code: string; region: string };
+
+const regionCountryOptions: RegionCountryOption[] = [
+  { label: "India", code: "in", region: "Asia" },
+  { label: "Afghanistan", code: "af", region: "Asia" },
+  { label: "UAE", code: "ae", region: "Asia" },
+  { label: "Albania", code: "al", region: "Europe" },
+  { label: "Andorra", code: "ad", region: "Europe" },
+  { label: "Argentina", code: "ar", region: "South America" },
+  { label: "Australia", code: "au", region: "Oceania" },
+  { label: "Algeria", code: "dz", region: "Africa" },
+];
+
+const meta: Meta<typeof Selector> = {
+  title: "Design System/Selector",
+  component: Selector,
+  tags: [],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: "24px", maxWidth: "420px" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    label: "Select Country",
+    placeholder: "Select a country",
+    error: "",
+    helperText: "",
+    size: "md",
+    options: countryOptions,
+    value: null,
+    color: "grey",
+  } as SelectorProps<SelectorOption>,
+  argTypes: {
+    color: {
+      control: { type: "radio" },
+      options: ["grey", "white"],
+    },
+    size: {
+      control: { type: "radio" },
+      options: ["xs", "sm", "md", "lg"],
+      description: "Size of the select scroll field",
+    },
+    error: {
+      control: { type: "text" },
+      description: "Error message displayed when in error state",
+    },
+    helperText: {
+      control: { type: "text" },
+      description: "Helper text displayed when not in error state",
+    },
+    disabled: {
+      control: { type: "boolean" },
+      description: "Disables the field",
+    },
+    loading: {
+      control: { type: "boolean" },
+      description: "Shows loading state",
+    },
+    loadingText: {
+      control: { type: "text" },
+      description: "Text shown when loading",
+    },
+    noOptionsText: {
+      control: { type: "text" },
+      description: "Text shown when no options are available",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Selector>;
+
+export const Playground: Story = {
+  args: {
+    label: "Select Country",
+    placeholder: "Select a country",
+    options: countryOptions,
+    value: null,
+    multiple: false,
+  },
+  render: (args) => {
+    const [value, setValue] = useState<any>(args.value);
+
+    // Sync external control changes if any
+    React.useEffect(() => {
+      setValue(args.value);
+    }, [args.value]);
+
+    return (
+      <Selector
+        {...args}
+        value={value}
+        onChange={(newValue) => {
+          setValue(newValue);
+        }}
+      />
+    );
+  },
+};
+
+const ShowcaseComponent = () => {
+  const [singleValue1, setSingleValue1] = useState<string | null>(null);
+  const [singleValue2, setSingleValue2] = useState<string | null>("Jim Beam");
+  const [singleValue3, setSingleValue3] = useState<string | null>(null);
+  const [singleValue4, setSingleValue4] = useState<string | null>(null);
+  const [singleValue5, setSingleValue5] = useState<string | null>("India");
+  const [singleValue6, setSingleValue6] = useState<string | null>(null);
+  const [singleValue7, setSingleValue7] = useState<string | null>(null);
+  const [singleValue8, setSingleValue8] = useState<{
+    label: string;
+    code: string;
+  } | null>(null);
+  const [singleValue9, setSingleValue9] = useState<RegionCountryOption | null>(
+    null,
+  );
+  const [singleValue10, setSingleValue10] =
+    useState<RegionCountryOption | null>(null);
+
+  const [multipleValue1, setMultipleValue1] = useState<string[]>([]);
+  const [multipleValue2, setMultipleValue2] = useState<string[]>([
+    "India",
+    "UAE",
+    "Australia",
+  ]);
+  const [multipleValue3, setMultipleValue3] = useState<string[]>([
+    "India",
+    "Afghanistan",
+    "UAE",
+    "Albania",
+    "Algeria",
+    "Argentina",
+  ]);
+  const [multipleValue4, setMultipleValue4] = useState<string[]>([
+    "India",
+    "UAE",
+  ]);
+  const [multipleValue5, setMultipleValue5] = useState<string[]>([
+    "India",
+    "UAE",
+  ]);
+  const [multipleValue6, setMultipleValue6] = useState<
+    { label: string; code: string }[]
+  >([]);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+      {/* Default / Empty */}
+      <Selector
+        label="Select Country"
+        placeholder="Select a country"
+        options={countryOptions}
+        value={singleValue1}
+        onChange={(value) => setSingleValue1(value as string | null)}
+      />
+
+      {/* Color: white */}
+      <Selector
+        label="Select Country (white)"
+        placeholder="Select a country"
+        options={countryOptions}
+        value={singleValue1}
+        onChange={(value) => setSingleValue1(value as string | null)}
+        color="white"
+      />
+
+      {/* With Value */}
+      <Selector
+        label="Username"
+        placeholder="Select a username"
+        options={usernameOptions}
+        value={singleValue2}
+        onChange={(value) => setSingleValue2(value as string | null)}
+      />
+
+      {/* Error State */}
+      <Selector
+        label="Select Country"
+        placeholder="Select a country"
+        options={countryOptions}
+        value={singleValue3}
+        onChange={(value) => setSingleValue3(value as string | null)}
+        error="Please select a valid country"
+      />
+
+      {/* With Helper Text */}
+      <Selector
+        label="Select Country"
+        placeholder="Select a country"
+        options={countryOptions}
+        value={singleValue4}
+        onChange={(value) => setSingleValue4(value as string | null)}
+        helperText="Select your country of residence"
+      />
+
+      {/* Disabled */}
+      <Selector
+        label="Select Country"
+        placeholder="Select a country"
+        options={countryOptions}
+        value={singleValue5}
+        onChange={(value) => setSingleValue5(value as string | null)}
+        disabled
+      />
+
+      {/* Extra Small Size */}
+      <Selector
+        label="Select Country"
+        placeholder="Select a country"
+        size="xs"
+        options={countryOptions}
+        value={singleValue6}
+        onChange={(value) => setSingleValue6(value as string | null)}
+      />
+
+      {/* Small Size */}
+      <Selector
+        label="Select Country"
+        placeholder="Select a country"
+        size="sm"
+        options={countryOptions}
+        value={singleValue7}
+        onChange={(value) => setSingleValue7(value as string | null)}
+      />
+
+      {/* With Object Options */}
+      <Selector
+        label="Select Country (Object)"
+        placeholder="Select a country"
+        options={countryObjectOptions}
+        value={singleValue8}
+        onChange={(value) =>
+          setSingleValue8(value as { label: string; code: string } | null)
+        }
+        getOptionLabel={(option) =>
+          typeof option === "string" ? option : option.label
+        }
+      />
+
+      {/* Grouped Options - Default Group UI */}
+      <Selector
+        label="Select Country (Grouped)"
+        placeholder="Search country"
+        options={regionCountryOptions}
+        value={singleValue9}
+        onChange={(value) =>
+          setSingleValue9(value as RegionCountryOption | null)
+        }
+        groupBy={(option) => option.region}
+      />
+
+      {/* Grouped Options - Custom renderGroup (MUI-style) */}
+      <Selector
+        label="Select Country (Grouped, Custom Render)"
+        placeholder="Search country"
+        options={regionCountryOptions}
+        value={singleValue10}
+        onChange={(value) =>
+          setSingleValue10(value as RegionCountryOption | null)
+        }
+        groupBy={(option) => option.region}
+        renderGroup={(params) => (
+          <ul style={{ listStyle: "none", margin: 0, padding: 0 }}>
+            {params.children}
+          </ul>
+        )}
+      />
+
+      {/* Multiple Select - Empty */}
+      <Selector
+        label="Select Countries (Multiple)"
+        placeholder="Select countries"
+        options={countryOptions}
+        value={multipleValue1}
+        onChange={(value) => setMultipleValue1(value as string[])}
+        multiple
+      />
+
+      {/* Multiple Select - With Values */}
+      <Selector
+        label="Selected Countries"
+        placeholder="Select countries"
+        options={countryOptions}
+        value={multipleValue2}
+        onChange={(value) => setMultipleValue2(value as string[])}
+        multiple
+      />
+
+      {/* Multiple Select - With Limit Tags */}
+      <Selector
+        label="Select Countries (Limited Tags)"
+        placeholder="Select countries"
+        options={countryOptions}
+        value={multipleValue3}
+        onChange={(value) => setMultipleValue3(value as string[])}
+        multiple
+        limitTags={3}
+      />
+
+      {/* Multiple Select - Disabled */}
+      <Selector
+        label="Select Countries (Disabled)"
+        placeholder="Select countries"
+        options={countryOptions}
+        value={multipleValue4}
+        onChange={(value) => setMultipleValue4(value as string[])}
+        multiple
+        disabled
+      />
+
+      {/* Multiple Select - Small Size */}
+      <Selector
+        label="Select Countries (Small)"
+        placeholder="Select countries"
+        options={countryOptions}
+        value={multipleValue5}
+        onChange={(value) => setMultipleValue5(value as string[])}
+        multiple
+        size="sm"
+      />
+
+      {/* Multiple Select - With Object Options */}
+      <Selector
+        label="Select Countries (Object, Multiple)"
+        placeholder="Select countries"
+        options={countryObjectOptions}
+        value={multipleValue6}
+        onChange={(value) =>
+          setMultipleValue6(value as { label: string; code: string }[])
+        }
+        multiple
+        getOptionLabel={(option) =>
+          typeof option === "string" ? option : option.label
+        }
+      />
+    </div>
+  );
+};
+
+export const Showcase: Story = {
+  render: () => <ShowcaseComponent />,
+};