@astryxdesign/lab 0.0.0-bootstrap.0 → 0.1.2-canary.04e71b2

package/src/Stepper/Stepper.tsx

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Stepper.tsx
+ * @input Uses React, stylex, theme tokens, StepperContext
+ * @output Exports Stepper component and StepperProps
+ * @position Core container component; consumed by index.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
+ * - /packages/lab/src/Stepper/Stepper.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/Stepper/index.ts (exports if types change)
+ * - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/Stepper/ (showcase blocks)
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {mergeProps} from '@astryxdesign/core/utils';
+import type {BaseProps} from '@astryxdesign/core';
+import {themeProps} from '@astryxdesign/core/utils';
+import {
+  StepperContext,
+  type StepperOrientation,
+  type StepperContextValue,
+} from './StepperContext';
+
+export interface StepperProps extends BaseProps<HTMLOListElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLOListElement>;
+  /**
+   * Zero-based index of the active step.
+   */
+  activeStep: number;
+  /**
+   * Step elements to render.
+   */
+  children: ReactNode;
+  /**
+   * Layout direction of the stepper.
+   * @default 'horizontal'
+   */
+  orientation?: StepperOrientation;
+  /**
+   * Called when a step indicator is clicked. Enables non-linear navigation.
+   * When provided, completed and current steps become clickable.
+   */
+  onStepClick?: (index: number) => void;
+  /**
+   * Accessible label describing the set of steps.
+   * @default 'Progress'
+   */
+  label?: string;
+  /**
+   * Controls density (padding) of all steps.
+   * @default 'balanced'
+   */
+  density?: 'compact' | 'balanced' | 'spacious';
+}
+
+const STEP_GAP = '2px';
+
+const styles = stylex.create({
+  root: {
+    display: 'flex',
+    width: '100%',
+    listStyleType: 'none',
+    margin: 0,
+    padding: 0,
+  },
+  horizontal: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: STEP_GAP,
+  },
+  vertical: {
+    flexDirection: 'column',
+    gap: STEP_GAP,
+  },
+});
+
+/**
+ * A stepper component for multi-step workflows. Displays numbered steps
+ * with visual indicators for completed, active, and upcoming states.
+ *
+ * Each Step child must provide a `step` prop (zero-based index) so it
+ * can derive its state from the parent's activeStep. CSS :last-child
+ * handles connector hiding — no child introspection needed.
+ *
+ * Rendered as an ordered list (`<ol>`/`<li>`) rather than a `nav`
+ * landmark: a stepper communicates *progress through a sequence*, not a
+ * set of site navigation links. The active step is marked with
+ * `aria-current="step"` (handled per-step) and the list carries an
+ * accessible `label`. This follows the WAI-ARIA pattern for steppers /
+ * progress sequences and avoids polluting the page's landmark map.
+ *
+ * @example
+ * ```
+ * <Stepper activeStep={1}>
+ *   <Step step={0} label="Account" />
+ *   <Step step={1} label="Profile" />
+ *   <Step step={2} label="Review" />
+ * </Stepper>
+ * ```
+ */
+export function Stepper({
+  activeStep,
+  children,
+  orientation = 'horizontal',
+  onStepClick,
+  label = 'Progress',
+  density = 'balanced',
+  xstyle,
+  className,
+  style,
+  ref,
+  ...rest
+}: StepperProps) {
+  const ctxValue = useMemo<StepperContextValue>(
+    () => ({
+      activeStep,
+      orientation,
+      isNonLinear: onStepClick != null,
+      onStepClick: onStepClick ?? null,
+      density,
+    }),
+    [activeStep, orientation, onStepClick, density],
+  );
+
+  return (
+    <StepperContext value={ctxValue}>
+      <ol
+        ref={ref}
+        aria-label={label}
+        {...rest}
+        {...mergeProps(
+          themeProps('stepper', {orientation}),
+          stylex.props(
+            styles.root,
+            orientation === 'horizontal' ? styles.horizontal : styles.vertical,
+            xstyle,
+          ),
+          className,
+          style,
+        )}>
+        {/* Each step renders its own progress bar segment; no child
+            introspection needed — steps derive state from context. */}
+        {children}
+      </ol>
+    </StepperContext>
+  );
+}
+
+Stepper.displayName = 'Stepper';

package/src/Stepper/StepperContext.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StepperContext.ts
+ * @input Uses React createContext/use
+ * @output Exports StepperContext, useStepperContext, and context types
+ * @position Context for Stepper <-> Step communication
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Stepper/Stepper.doc.mjs
+ * - /packages/lab/src/Stepper/index.ts
+ */
+
+import {createContext, use} from 'react';
+
+export type StepperOrientation = 'horizontal' | 'vertical';
+export type StepperDensity = 'compact' | 'balanced' | 'spacious';
+
+export interface StepperContextValue {
+  activeStep: number;
+  orientation: StepperOrientation;
+  isNonLinear: boolean;
+  onStepClick: ((index: number) => void) | null;
+  density: StepperDensity;
+}
+
+export const StepperContext = createContext<StepperContextValue | null>(
+  null,
+);
+StepperContext.displayName = 'StepperContext';
+
+export function useStepperContext(): StepperContextValue {
+  const ctx = use(StepperContext);
+  if (ctx == null) {
+    throw new Error(
+      'useStepperContext must be used within Stepper. ' +
+        'Wrap your Step in <Stepper>.',
+    );
+  }
+  return ctx;
+}

package/src/Stepper/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+export {Stepper} from './Stepper';
+export type {StepperProps} from './Stepper';
+
+export {Step} from './Step';
+export type {StepProps, StepIndicatorPreset} from './Step';
+
+export type {StepStatus} from './StepStatus';
+
+export {useStepperContext} from './StepperContext';
+export type {StepperOrientation} from './StepperContext';

package/src/ThreeD/3DBar.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: '3DBar',
+  displayName: '3D Bar',
+  group: 'ThreeD',
+  category: 'Data Visualization',
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ThreeD/3DChart.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: '3DChart',
+  displayName: '3D Chart',
+  group: 'ThreeD',
+  category: 'Data Visualization',
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ThreeD/3DScatter.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: '3DScatter',
+  displayName: '3D Scatter',
+  group: 'ThreeD',
+  category: 'Data Visualization',
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ThreeD/3DScatterGL.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: '3DScatterGL',
+  displayName: '3D Scatter GL',
+  group: 'ThreeD',
+  category: 'Data Visualization',
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ThreeD/3DSurface.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: '3DSurface',
+  displayName: '3D Surface',
+  group: 'ThreeD',
+  category: 'Data Visualization',
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ThreeD/ThreeDAxis.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDAxis.tsx
+ * @output 3D axis lines with labels at each end
+ */
+
+import {use3D} from './ThreeDContext';
+
+export interface ThreeDAxisProps {
+  /** Show axis labels (default: true) */
+  labels?: boolean;
+}
+
+export function ThreeDAxis({labels = true}: ThreeDAxisProps) {
+  const {project, xKey, yKey, zKey, xDomain, yDomain, zDomain} = use3D();
+
+  const origin = project(0, 0, 0);
+  const xEnd = project(1, 0, 0);
+  const yEnd = project(0, 1, 0);
+  const zEnd = project(0, 0, 1);
+
+  const lineColor = 'var(--color-border-emphasized)';
+  const labelColor = 'var(--color-text-secondary)';
+
+  return (
+    <g>
+      {/* X axis */}
+      <line
+        x1={origin.px}
+        y1={origin.py}
+        x2={xEnd.px}
+        y2={xEnd.py}
+        stroke={lineColor}
+        strokeWidth={1.5}
+      />
+      {/* Y axis */}
+      <line
+        x1={origin.px}
+        y1={origin.py}
+        x2={yEnd.px}
+        y2={yEnd.py}
+        stroke={lineColor}
+        strokeWidth={1.5}
+      />
+      {/* Z axis */}
+      <line
+        x1={origin.px}
+        y1={origin.py}
+        x2={zEnd.px}
+        y2={zEnd.py}
+        stroke={lineColor}
+        strokeWidth={1.5}
+      />
+
+      {labels && (
+        <>
+          <text
+            x={xEnd.px + 8}
+            y={xEnd.py}
+            fill={labelColor}
+            fontSize={11}
+            dominantBaseline="central">
+            {xKey} [{xDomain[0]}-{xDomain[1]}]
+          </text>
+          <text
+            x={yEnd.px + 8}
+            y={yEnd.py}
+            fill={labelColor}
+            fontSize={11}
+            dominantBaseline="central">
+            {yKey} [{yDomain[0]}-{yDomain[1]}]
+          </text>
+          <text
+            x={zEnd.px + 8}
+            y={zEnd.py}
+            fill={labelColor}
+            fontSize={11}
+            dominantBaseline="central">
+            {zKey} [{zDomain[0]}-{zDomain[1]}]
+          </text>
+        </>
+      )}
+    </g>
+  );
+}

package/src/ThreeD/ThreeDBar.tsx

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDBar.tsx
+ * @output 3D bar chart — projected rectangles with depth shading
+ */
+
+import {useMemo} from 'react';
+import {use3D} from './ThreeDContext';
+
+export interface ThreeDBarProps {
+  color: string;
+  barWidth?: number;
+  barDepth?: number;
+}
+
+export function ThreeDBar({
+  color,
+  barWidth = 0.06,
+  barDepth = 0.06,
+}: ThreeDBarProps) {
+  const {
+    data,
+    xKey,
+    yKey,
+    zKey,
+    project,
+    xDomain,
+    yDomain,
+    zDomain,
+    normalize,
+  } = use3D();
+
+  const bars = useMemo(() => {
+    return data
+      .map((d, i) => {
+        const nx = normalize(d[xKey] as number, xDomain);
+        const ny = normalize(d[yKey] as number, yDomain);
+        const nz = normalize(d[zKey] as number, zDomain);
+        const hw = barWidth / 2;
+        const hd = barDepth / 2;
+
+        // Bar goes from y=0 to y=ny
+        // Four top corners of the bar
+        const topFL = project(nx - hw, ny, nz - hd); // front-left
+        const topFR = project(nx + hw, ny, nz - hd); // front-right
+        const topBL = project(nx - hw, ny, nz + hd); // back-left
+        const topBR = project(nx + hw, ny, nz + hd); // back-right
+
+        // Four bottom corners (y=0)
+        const botFL = project(nx - hw, 0, nz - hd);
+        const botFR = project(nx + hw, 0, nz - hd);
+        const botBL = project(nx - hw, 0, nz + hd);
+        const botBR = project(nx + hw, 0, nz + hd);
+
+        // Average depth for sorting
+        const avgDepth =
+          (topFL.depth + topBR.depth + botFL.depth + botBR.depth) / 4;
+
+        return {
+          topFL,
+          topFR,
+          topBL,
+          topBR,
+          botFL,
+          botFR,
+          botBL,
+          botBR,
+          avgDepth,
+          index: i,
+          ny,
+        };
+      })
+      .sort((a, b) => a.avgDepth - b.avgDepth);
+  }, [
+    data,
+    xKey,
+    yKey,
+    zKey,
+    project,
+    xDomain,
+    yDomain,
+    zDomain,
+    normalize,
+    barWidth,
+    barDepth,
+  ]);
+
+  return (
+    <g>
+      {bars.map(b => {
+        const face = (pts: {px: number; py: number}[], _shade: number) =>
+          pts.map(p => `${p.px},${p.py}`).join(' ');
+
+        // Front face
+        const front = [b.botFL, b.botFR, b.topFR, b.topFL];
+        // Right face
+        const right = [b.botFR, b.botBR, b.topBR, b.topFR];
+        // Top face
+        const top = [b.topFL, b.topFR, b.topBR, b.topBL];
+
+        return (
+          <g key={b.index}>
+            <polygon
+              points={face(front, 0)}
+              fill={color}
+              fillOpacity={0.9}
+              stroke={color}
+              strokeWidth={0.5}
+            />
+            <polygon
+              points={face(right, 0)}
+              fill={color}
+              fillOpacity={0.7}
+              stroke={color}
+              strokeWidth={0.5}
+            />
+            <polygon
+              points={face(top, 0)}
+              fill={color}
+              fillOpacity={1}
+              stroke={color}
+              strokeWidth={0.5}
+            />
+          </g>
+        );
+      })}
+    </g>
+  );
+}