@arbor-education/design-system.components 0.6.0 → 0.8.0

package/src/components/tag/Tag.tsx

@@ -1,4 +1,5 @@
 import classNames from 'classnames';
+import { Icon } from 'Components/icon/Icon';
 
 export type TagColor = 'neutral'
   | 'orange'
@@ -9,26 +10,49 @@ export type TagColor = 'neutral'
   | 'salmon'
   | 'yellow';
 
-export type DotColour = 'purple' | 'salmon' | 'teal' | 'yellow' | 'green' | 'orange' | 'blue';
-
-type TagProps = {
-  text: string;
+export type TagProps = {
+  children: React.ReactNode;
   color?: TagColor;
-  dotColour?: DotColour;
+  selected?: boolean;
+  slotStart?: React.ReactNode;
+  slotEnd?: React.ReactNode;
+  onRemove?: () => void;
+  removeLabel?: string;
+  removeButtonTabIndex?: 0 | -1;
 };
 
-export const Tag = ({ text, color = 'neutral', dotColour }: TagProps) => {
+export const Tag = ({
+  children,
+  color = 'neutral',
+  selected = false,
+  slotStart,
+  slotEnd,
+  onRemove,
+  removeLabel = 'Remove',
+  removeButtonTabIndex = 0,
+}: TagProps): React.JSX.Element => {
   return (
-    <span
-      className={classNames('ds-tag', `ds-tag--${color}`)}
+    <span className={classNames('ds-tag', `ds-tag--${color}`, {
+      'ds-tag--selected': selected,
+    })}
     >
-      {dotColour && (
-        <span
-          aria-label={`${dotColour} dot`}
-          className={classNames('ds-tag__dot', `ds-tag__dot--${dotColour}`)}
-        />
+      {slotStart && <span className="ds-tag__slot-start">{slotStart}</span>}
+      <span className="ds-tag__label">{children}</span>
+      {slotEnd && <span className="ds-tag__slot-end">{slotEnd}</span>}
+      {onRemove && (
+        <button
+          type="button"
+          className="ds-tag__remove"
+          aria-label={removeLabel}
+          onClick={(e) => {
+            e.stopPropagation();
+            onRemove();
+          }}
+          tabIndex={removeButtonTabIndex}
+        >
+          <Icon name="x" size={12} />
+        </button>
       )}
-      {text}
     </span>
   );
 };

package/src/components/tag/tag.scss

@@ -1,21 +1,24 @@
 .ds-tag {
-  display: flex;
-  padding: var(--tag-spacing-vertical) var(--tag-spacing-horizontal);
+  display: inline-flex;
+  padding: 0 var(--tag-spacing-horizontal);
   align-items: center;
   gap: var(--tag-spacing-gap-horizontal);
   border-radius: var(--tag-radius);
+  border: var(--border-weight) solid transparent;
+  box-sizing: border-box;
   flex-grow: 0;
   width: fit-content;
-
-  /* typography/body/p1-reg */
+  white-space: nowrap;
+  max-width: 100%;
+  height: var(--tag-height);
   font-style: normal;
-  line-height: 150%; /* 19.5px */
+  line-height: 150%;
 
   &--neutral {
     color: var(--tag-neutral-color-text);
     background: var(--tag-neutral-color-background);
   }
-  
+
   &--orange {
     color: var(--tag-category-orange-color-text);
     background: var(--tag-category-orange-color-background);
@@ -50,38 +53,50 @@
     color: var(--tag-category-yellow-color-text);
     background: var(--tag-category-yellow-color-background);
   }
-}
 
-.ds-tag__dot {
-  width: 10px;
-  height: 10px;
-  border-radius: 50%;
-
-  &--purple {
-    background-color: var(--color-extended-colours-purple-500);
+  &--selected {
+    background: var(--tag-selected-color-background);
+    color: var(--tag-neutral-color-text);
+    border-color: var(--tag-selected-color-border);
   }
 
-  &--salmon {
-    background-color: var(--color-extended-colours-salmon-500);
-  }
+}
 
-  &--teal {
-    background-color: var(--color-extended-colours-teal-500);
-  }
+.ds-tag__slot-start {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
 
-  &--yellow {
-    background-color: var(--color-extended-colours-yellow-500);
-  }
+.ds-tag__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
 
-  &--green {
-    background-color: var(--color-extended-colours-green-500);
-  }
+.ds-tag__slot-end {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
 
-  &--orange {
-    background-color: var(--color-extended-colours-orange-500);
+.ds-tag__remove {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  padding: 0;
+  cursor: pointer;
+  color: inherit;
+  border-radius: 50%;
+  flex-shrink: 0;
+
+  &:hover {
+    background-color: var(--color-grey-200);
   }
 
-  &--blue {
-    background-color: var(--color-extended-colours-blue-500);
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
   }
 }

package/src/components/toggle/Toggle.stories.tsx

@@ -0,0 +1,239 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { fn } from 'storybook/test';
+import { Toggle } from './Toggle';
+
+/**
+ * The Toggle component is a binary on/off switch, built on top of Radix UI's
+ * Switch primitive. Think of it like the light switch in the St. Olaf town
+ * hall — everyone in town knows exactly whether the lights are on or off,
+ * and there is never any confusion about which state you are in.
+ *
+ * Toggling is the right choice when you need an immediate, binary setting
+ * change — "dark mode on", "notifications off", "feature enabled". Unlike a
+ * checkbox, a toggle implies the change takes effect right away, without
+ * needing a form submission.
+ *
+ * **Accessibility**
+ * - Rendered as a `<button role="switch">` — screen readers announce the
+ *   current state ("checked" / "not checked") automatically.
+ * - Fully keyboard accessible: `Space` or `Enter` toggles the state.
+ * - Associate a visible label with the toggle using a `<label htmlFor={id}>`
+ *   so users of all abilities know what they are toggling.
+ * - The `disabled` prop renders the element as non-interactive and applies
+ *   correct ARIA semantics.
+ *
+ * **CSS classes**
+ * - Root element: `ds-toggle`
+ * - Thumb (the sliding dot): `ds-toggle__thumb`
+ * - Checked state is driven by Radix's `data-state="checked"` attribute,
+ *   which the SCSS uses to apply brand colours and shift the thumb position.
+ */
+const meta = {
+  title: 'Components/Toggle',
+  component: Toggle,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  args: {
+    onCheckedChange: fn(),
+  },
+  argTypes: {
+    checked: {
+      control: 'boolean',
+      description:
+        'Controls the checked state when used as a controlled component. '
+        + 'Pair with `onCheckedChange` to keep your state in sync.',
+    },
+    defaultChecked: {
+      control: 'boolean',
+      description:
+        'Sets the initial checked state for an uncontrolled toggle. '
+        + 'The component manages its own state after mount.',
+    },
+    disabled: {
+      control: 'boolean',
+      description:
+        'Disables the toggle. The toggle becomes non-interactive and is '
+        + 'visually dimmed. Useful for read-only settings or permission-gated features.',
+    },
+    required: {
+      control: 'boolean',
+      description:
+        'Marks the toggle as required when used inside a `<form>`. '
+        + 'Prevents form submission if the toggle is unchecked.',
+    },
+    name: {
+      control: 'text',
+      description:
+        'The name of the toggle as submitted with form data. '
+        + 'Works the same as the `name` attribute on a native `<input>`.',
+    },
+    value: {
+      control: 'text',
+      description:
+        'The value submitted with form data when the toggle is checked. '
+        + 'Defaults to `"on"` (matching native checkbox behaviour).',
+    },
+    onCheckedChange: {
+      action: 'checkedChange',
+      description:
+        'Callback fired whenever the checked state changes. '
+        + 'Receives the new boolean value: `(checked: boolean) => void`.',
+    },
+  },
+} satisfies Meta<typeof Toggle>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Basic states
+// ---------------------------------------------------------------------------
+
+/** The toggle in its default, unchecked (off) state. */
+export const Default: Story = {};
+
+/**
+ * The toggle in its checked (on) state.
+ *
+ * Uses `defaultChecked` so the component manages its own state — perfect for
+ * uncontrolled usage where you just need a sensible starting position.
+ */
+export const Checked: Story = {
+  args: {
+    defaultChecked: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Disabled states
+// ---------------------------------------------------------------------------
+
+/**
+ * A disabled toggle that is currently off.
+ *
+ * Use this when a setting exists but cannot be changed in the current context
+ * — for example, a feature that requires a higher subscription tier.
+ */
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};
+
+/**
+ * A disabled toggle that is currently on.
+ *
+ * This communicates "this setting is enabled, but you cannot change it right
+ * now." Always pair a disabled toggle with a tooltip or helper text that
+ * explains why it cannot be interacted with.
+ */
+export const DisabledChecked: Story = {
+  args: {
+    defaultChecked: true,
+    disabled: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Controlled usage
+// ---------------------------------------------------------------------------
+
+/**
+ * A fully controlled toggle backed by React state.
+ *
+ * Back in St. Olaf, my neighbour Hildegard Bjornsson kept a hand-written
+ * ledger of every switch in her house — she never trusted a switch to remember
+ * its own state! A controlled toggle is just like that ledger: your component
+ * owns the truth, and the toggle simply displays what you tell it to.
+ *
+ * Use the controlled pattern when:
+ * - You need to read the toggle state elsewhere in the UI.
+ * - You want to conditionally show/hide other elements based on the state.
+ * - You are submitting state as part of a larger form payload.
+ */
+const ControlledTemplate = (args: React.ComponentProps<typeof Toggle>) => {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: '12px',
+      }}
+    >
+      <Toggle
+        {...args}
+        checked={enabled}
+        onCheckedChange={(checked) => {
+          setEnabled(checked);
+          args.onCheckedChange?.(checked);
+        }}
+      />
+      <p
+        style={{
+          margin: 0,
+          fontSize: '14px',
+          color: enabled ? 'var(--color-brand-700)' : 'var(--color-grey-500)',
+        }}
+      >
+        {enabled ? 'Feature enabled' : 'Feature disabled'}
+      </p>
+    </div>
+  );
+};
+
+export const Controlled: Story = {
+  render: ControlledTemplate,
+};
+
+// ---------------------------------------------------------------------------
+// With label (accessible usage)
+// ---------------------------------------------------------------------------
+
+/**
+ * A toggle paired with a visible `<label>` element for full accessibility.
+ *
+ * This is the pattern you should reach for in almost every real-world use
+ * case. By wiring the label's `htmlFor` to the toggle's `id`, you get:
+ *
+ * - Screen readers announce both the label text and the toggle state.
+ * - Clicking the label text also toggles the switch (larger click target).
+ * - Visual users see a clear description of what the toggle controls.
+ *
+ * You know, this is a lot like what we learned in St. Olaf Home Economics
+ * class — always label your preserves. An unlabelled jar of lingonberry jam
+ * looks just like an unlabelled jar of beet relish, and nobody wants that
+ * confusion at the dinner table. Or on a settings page!
+ */
+const WithLabelTemplate = (args: React.ComponentProps<typeof Toggle>) => {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+      <Toggle
+        {...args}
+        id="email-notifications-toggle"
+        checked={enabled}
+        onCheckedChange={(checked) => {
+          setEnabled(checked);
+          args.onCheckedChange?.(checked);
+        }}
+      />
+      <label
+        htmlFor="email-notifications-toggle"
+        style={{ fontSize: '14px', cursor: 'pointer', userSelect: 'none' }}
+      >
+        Email notifications
+      </label>
+    </div>
+  );
+};
+
+export const WithLabel: Story = {
+  render: WithLabelTemplate,
+};

package/src/components/toggle/Toggle.test.tsx

@@ -0,0 +1,66 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { Toggle } from './Toggle';
+
+describe('Toggle component', () => {
+  test('renders a switch element', () => {
+    render(<Toggle />);
+    expect(screen.getByRole('switch')).toBeInTheDocument();
+  });
+
+  test('is unchecked by default', () => {
+    render(<Toggle />);
+    expect(screen.getByRole('switch')).not.toBeChecked();
+  });
+
+  test('is checked when defaultChecked is true', () => {
+    render(<Toggle defaultChecked />);
+    expect(screen.getByRole('switch')).toBeChecked();
+  });
+
+  test('is checked when controlled checked prop is true', () => {
+    render(<Toggle checked onCheckedChange={vi.fn()} />);
+    expect(screen.getByRole('switch')).toBeChecked();
+  });
+
+  test('calls onCheckedChange with true when toggled on', () => {
+    const handleChange = vi.fn();
+    render(<Toggle onCheckedChange={handleChange} />);
+    fireEvent.click(screen.getByRole('switch'));
+    expect(handleChange).toHaveBeenCalledTimes(1);
+    expect(handleChange).toHaveBeenCalledWith(true);
+  });
+
+  test('calls onCheckedChange with false when toggled off', () => {
+    const handleChange = vi.fn();
+    render(<Toggle defaultChecked onCheckedChange={handleChange} />);
+    fireEvent.click(screen.getByRole('switch'));
+    expect(handleChange).toHaveBeenCalledTimes(1);
+    expect(handleChange).toHaveBeenCalledWith(false);
+  });
+
+  test('is disabled when disabled prop is set', () => {
+    render(<Toggle disabled />);
+    expect(screen.getByRole('switch')).toBeDisabled();
+  });
+
+  test('does not call onCheckedChange when disabled', () => {
+    const handleChange = vi.fn();
+    render(<Toggle disabled onCheckedChange={handleChange} />);
+    fireEvent.click(screen.getByRole('switch'));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  test('applies the ds-toggle base class', () => {
+    render(<Toggle />);
+    expect(screen.getByRole('switch')).toHaveClass('ds-toggle');
+  });
+
+  test('applies additional className alongside base class', () => {
+    render(<Toggle className="custom-class" />);
+    const toggle = screen.getByRole('switch');
+    expect(toggle).toHaveClass('ds-toggle');
+    expect(toggle).toHaveClass('custom-class');
+  });
+});

package/src/components/toggle/Toggle.tsx

@@ -0,0 +1,12 @@
+import classNames from 'classnames';
+import { Switch } from 'radix-ui';
+
+export const Toggle = (props: Switch.SwitchProps) => {
+  const { className, ...rest } = props;
+
+  return (
+    <Switch.Root className={classNames('ds-toggle', className)} {...rest}>
+      <Switch.Thumb className="ds-toggle__thumb" />
+    </Switch.Root>
+  );
+};

package/src/components/toggle/toggle.scss

@@ -0,0 +1,126 @@
+.ds-toggle {
+  all: unset;
+  width: 40px;
+  height: 24px;
+  background-color: var(--toggle-off-default-color-background);
+  border-radius: var(--toggle-radius);
+  border: var(--toggle-weight-border) solid var(--toggle-off-default-color-border);
+  position: relative;
+  cursor: pointer;
+
+  &:focus {
+    background-color: var(--toggle-off-focus-color-background);
+    border-color: var(--toggle-off-focus-color-border);
+    outline: var(--focus-border) solid var(--color-brand-300);
+  }
+
+  &:hover {
+    background-color: var(--toggle-off-hover-color-background);
+    border-color: var(--toggle-off-hover-color-border);
+  }
+  
+  &:active {
+    background-color: var(--toggle-off-active-color-background);
+    border-color: var(--toggle-off-active-color-border);
+  }
+
+  &:disabled {
+    background-color: var(--toggle-off-disabled-color-background);
+    border-color: var(--toggle-off-disabled-color-border);
+    cursor: default;
+
+    &:focus, &:hover, &:active {
+      background-color: var(--toggle-off-disabled-color-background);
+      border-color: var(--toggle-off-disabled-color-border);
+      outline: none;
+    }
+  }
+
+  &[data-state="checked"] {
+    background-color: var(--toggle-on-default-color-background);
+    border-color: var(--toggle-on-default-color-border);
+
+    &:focus {
+      background-color: var(--toggle-on-focus-color-background);
+      border-color: var(--toggle-on-focus-color-border);
+    }
+
+    &:hover {
+      background-color: var(--toggle-on-hover-color-background);
+      border-color: var(--toggle-on-hover-color-border);
+    }
+
+    &:active {
+      background-color: var(--toggle-on-active-color-background);
+      border-color: var(--toggle-on-active-color-border);
+    }
+
+    &:disabled {
+      background-color: var(--toggle-on-disabled-color-background);
+      border-color: var(--toggle-on-disabled-color-border);
+      cursor: default;
+      
+      &:focus, &:hover, &:active {
+        background-color: var(--toggle-on-disabled-color-background);
+        border-color: var(--toggle-on-disabled-color-border);
+        outline: none;
+      }
+    }
+  }
+
+  &__thumb {
+    display: block;
+    width: 18px;
+    height: 18px;
+    background-color: var(--toggle-off-default-color-dot);
+    border-radius: var(--border-radius-round);
+    transition: transform .1s;
+    transform: translateX(2px);
+    will-change: transform;
+
+    &:focus {
+      background-color: var(--toggle-off-focus-color-dot);
+    }
+
+    &:hover {
+      background-color: var(--toggle-off-hover-color-dot);
+    }
+
+    &:active {
+      background-color: var(--toggle-off-active-color-dot);
+    }
+
+    &[data-disabled] {
+      background-color: var(--toggle-off-disabled-color-dot);
+
+      &:focus, &:hover, &:active {
+        background-color: var(--toggle-off-disabled-color-dot);
+      }
+    }
+
+    &[data-state="checked"] {
+      transform: translateX(20px);
+      background-color: var(--toggle-on-default-color-dot);
+
+      &:focus {
+        background-color: var(--toggle-on-focus-color-dot);
+      }
+
+      &:hover {
+        background-color: var(--toggle-on-hover-color-dot);
+      }
+
+      &:active {
+        background-color: var(--toggle-on-active-color-dot);
+      }
+
+      &[data-disabled] {
+        background-color: var(--toggle-on-disabled-color-dot);
+
+        &:focus, &:hover, &:active {
+          background-color: var(--toggle-on-disabled-color-dot);
+        }
+      }
+    }
+  }
+}

package/src/index.scss

@@ -16,6 +16,8 @@
 @use "components/formField/inputs/selectDropdown/selectDropdown";
 @use "components/formField/inputs/colourPickerDropdown/colourPickerDropdown.scss";
 @use "components/tag/tag.scss";
+@use "components/dot/dot.scss";
+@use "components/badge/badge.scss";
 @use "components/pill/pill.scss";
 @use "components/section/section.scss";
 @use "components/tabs/tabs.scss";
@@ -35,6 +37,10 @@
 @use "components/toast/toast.scss";
 @use "components/datePicker/datePicker.scss";
 @use "components/avatar/avatar.scss";
+@use "components/singleUser/singleUser.scss";
 @use "components/avatarGroup/avatarGroup.scss";
 @use "components/userDropdown/userDropdown.scss";
+@use "components/row/row.scss";
+@use "components/combobox/combobox.scss";
+@use "components/toggle/toggle.scss";
 @import "https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap";