@fragments-sdk/ui 0.1.0

package/src/components/Textarea/Textarea.fragment.tsx

@@ -0,0 +1,171 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Textarea } from './index.js';
+
+export default defineSegment({
+  component: Textarea,
+
+  meta: {
+    name: 'Textarea',
+    description: 'Multi-line text input for longer form content',
+    category: 'forms',
+    status: 'stable',
+    tags: ['input', 'text', 'form', 'multiline'],
+  },
+
+  usage: {
+    when: [
+      'Collecting multi-line text (comments, descriptions)',
+      'Free-form text input that may span multiple lines',
+      'Message composition fields',
+      'Code or content editing',
+    ],
+    whenNot: [
+      'Single-line input (use Input)',
+      'Rich text editing (use rich text editor)',
+      'Selecting from predefined options (use Select)',
+    ],
+    guidelines: [
+      'Set appropriate rows for expected content length',
+      'Use placeholder to show example format',
+      'Show character count when maxLength is set',
+      'Consider auto-resize for better UX',
+    ],
+    accessibility: [
+      'Always provide a visible label',
+      'Use helperText for format hints',
+      'Error messages should be descriptive',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'string',
+      description: 'Controlled value',
+    },
+    placeholder: {
+      type: 'string',
+      description: 'Placeholder text',
+    },
+    rows: {
+      type: 'number',
+      default: 3,
+      description: 'Number of visible text rows',
+    },
+    label: {
+      type: 'string',
+      description: 'Label text above the textarea',
+    },
+    helperText: {
+      type: 'string',
+      description: 'Helper text below the textarea',
+    },
+    error: {
+      type: 'boolean',
+      default: false,
+      description: 'Error state',
+    },
+    disabled: {
+      type: 'boolean',
+      default: false,
+      description: 'Disabled state',
+    },
+    resize: {
+      type: 'enum',
+      values: ['none', 'vertical', 'horizontal', 'both'],
+      default: 'vertical',
+      description: 'Resize behavior',
+    },
+    maxLength: {
+      type: 'number',
+      description: 'Maximum character length',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Input',
+      relationship: 'alternative',
+      note: 'Use Input for single-line text',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - controlled value',
+      'rows: number - visible rows (default: 3)',
+      'label: string - label text',
+      'error: boolean - error state',
+      'disabled: boolean - disabled state',
+      'resize: none|vertical|horizontal|both',
+    ],
+    scenarioTags: [
+      'form.textarea',
+      'form.comment',
+      'form.description',
+    ],
+    a11yRules: [
+      'A11Y_LABEL_REQUIRED',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic textarea with label',
+      render: () => (
+        <Textarea
+          label="Description"
+          placeholder="Enter a description..."
+        />
+      ),
+    },
+    {
+      name: 'With Helper Text',
+      description: 'Textarea with additional guidance',
+      render: () => (
+        <Textarea
+          label="Bio"
+          placeholder="Tell us about yourself..."
+          helperText="Max 500 characters"
+          maxLength={500}
+        />
+      ),
+    },
+    {
+      name: 'Error State',
+      description: 'Textarea showing validation error',
+      render: () => (
+        <Textarea
+          label="Comments"
+          placeholder="Add your comments..."
+          error
+          helperText="This field is required"
+        />
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Non-interactive textarea',
+      render: () => (
+        <Textarea
+          label="Notes"
+          placeholder="Cannot edit..."
+          disabled
+        />
+      ),
+    },
+    {
+      name: 'Custom Rows',
+      description: 'Textarea with more visible rows',
+      render: () => (
+        <Textarea
+          label="Long Description"
+          placeholder="Enter detailed information..."
+          rows={6}
+        />
+      ),
+    },
+  ],
+});

package/src/components/Textarea/Textarea.module.scss

@@ -0,0 +1,89 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.wrapper {
+  display: flex;
+  flex-direction: column;
+}
+
+.label {
+  @include label-text;
+  margin-bottom: var(--fui-space-1, $fui-space-1);
+}
+
+.required {
+  color: var(--fui-color-danger, $fui-color-danger);
+  margin-left: 2px;
+}
+
+.textarea {
+  @include text-base;
+  @include interactive-base;
+
+  display: block;
+  width: 100%;
+  min-height: var(--fui-input-height, $fui-input-height);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  line-height: $fui-line-height-normal;
+  font-family: inherit;
+
+  &::placeholder {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:hover:not(:disabled):not(:focus) {
+    border-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:focus {
+    @include focus-ring;
+    border-color: var(--fui-color-accent, $fui-color-accent);
+  }
+
+  &:disabled,
+  &[data-disabled] {
+    background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+// Resize variants
+.resize-none {
+  resize: none;
+}
+
+.resize-vertical {
+  resize: vertical;
+}
+
+.resize-horizontal {
+  resize: horizontal;
+}
+
+.resize-both {
+  resize: both;
+}
+
+// Error state
+.error {
+  border-color: var(--fui-color-danger, $fui-color-danger);
+
+  &:focus {
+    border-color: var(--fui-color-danger, $fui-color-danger);
+    box-shadow:
+      0 0 0 var(--fui-focus-ring-offset, $fui-focus-ring-offset) var(--fui-bg-primary, $fui-bg-primary),
+      0 0 0 calc(var(--fui-focus-ring-offset, $fui-focus-ring-offset) + var(--fui-focus-ring-width, $fui-focus-ring-width)) var(--fui-color-danger, $fui-color-danger);
+  }
+}
+
+.helper {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}
+
+.helperError {
+  color: var(--fui-color-danger, $fui-color-danger);
+}

package/src/components/Textarea/index.tsx

@@ -0,0 +1,128 @@
+import * as React from 'react';
+import styles from './Textarea.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface TextareaProps {
+  /** Controlled value */
+  value?: string;
+  /** Default value for uncontrolled usage */
+  defaultValue?: string;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Number of visible text rows */
+  rows?: number;
+  /** Minimum number of rows (for auto-resize) */
+  minRows?: number;
+  /** Maximum number of rows (for auto-resize) */
+  maxRows?: number;
+  /** Allow user to resize the textarea */
+  resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+  /** Disabled state */
+  disabled?: boolean;
+  /** Error state */
+  error?: boolean;
+  /** Label text above the textarea */
+  label?: string;
+  /** Helper text below the textarea */
+  helperText?: string;
+  /** Called when value changes */
+  onChange?: (value: string) => void;
+  /** Called when textarea loses focus */
+  onBlur?: () => void;
+  /** Additional class name */
+  className?: string;
+  /** Form field name */
+  name?: string;
+  /** Element ID */
+  id?: string;
+  /** Maximum character length */
+  maxLength?: number;
+  /** Required field */
+  required?: boolean;
+}
+
+export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  function Textarea(
+    {
+      value,
+      defaultValue,
+      placeholder,
+      rows = 3,
+      minRows,
+      maxRows,
+      resize = 'vertical',
+      disabled = false,
+      error = false,
+      label,
+      helperText,
+      onChange,
+      onBlur,
+      className,
+      name,
+      id,
+      maxLength,
+      required = false,
+    },
+    ref
+  ) {
+    const textareaId = id || React.useId();
+    const helperId = `${textareaId}-helper`;
+
+    const textareaClasses = [
+      styles.textarea,
+      error && styles.error,
+      styles[`resize-${resize}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const helperClasses = [styles.helper, error && styles.helperError]
+      .filter(Boolean)
+      .join(' ');
+
+    // Calculate min/max height based on rows
+    const style: React.CSSProperties = {};
+    if (minRows) {
+      style.minHeight = `calc(${minRows} * 1.5em + 1.5rem)`;
+    }
+    if (maxRows) {
+      style.maxHeight = `calc(${maxRows} * 1.5em + 1.5rem)`;
+    }
+
+    return (
+      <div className={styles.wrapper}>
+        {label && (
+          <label htmlFor={textareaId} className={styles.label}>
+            {label}
+            {required && <span className={styles.required}>*</span>}
+          </label>
+        )}
+        <textarea
+          ref={ref}
+          id={textareaId}
+          value={value}
+          defaultValue={defaultValue}
+          placeholder={placeholder}
+          rows={rows}
+          name={name}
+          maxLength={maxLength}
+          disabled={disabled}
+          required={required}
+          aria-invalid={error || undefined}
+          aria-describedby={helperText ? helperId : undefined}
+          onChange={(e) => onChange?.(e.target.value)}
+          onBlur={onBlur}
+          className={textareaClasses}
+          style={Object.keys(style).length > 0 ? style : undefined}
+        />
+        {helperText && (
+          <span id={helperId} className={helperClasses}>
+            {helperText}
+          </span>
+        )}
+      </div>
+    );
+  }
+);

package/src/components/Toast/Toast.fragment.tsx

@@ -0,0 +1,210 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Toast, ToastProvider, useToast } from './index.js';
+
+// Demo component that triggers toasts
+function ToastDemo() {
+  const { success, error, warning, info, toast } = useToast();
+
+  return (
+    <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+      <button
+        onClick={() => success('Success!', 'Your changes have been saved.')}
+        style={{ padding: '8px 16px', borderRadius: '6px', border: '1px solid #10b981', background: '#ecfdf5', color: '#065f46', cursor: 'pointer' }}
+      >
+        Success Toast
+      </button>
+      <button
+        onClick={() => error('Error', 'Something went wrong. Please try again.')}
+        style={{ padding: '8px 16px', borderRadius: '6px', border: '1px solid #ef4444', background: '#fef2f2', color: '#991b1b', cursor: 'pointer' }}
+      >
+        Error Toast
+      </button>
+      <button
+        onClick={() => warning('Warning', 'This action cannot be undone.')}
+        style={{ padding: '8px 16px', borderRadius: '6px', border: '1px solid #f59e0b', background: '#fffbeb', color: '#92400e', cursor: 'pointer' }}
+      >
+        Warning Toast
+      </button>
+      <button
+        onClick={() => info('Info', 'New features are available.')}
+        style={{ padding: '8px 16px', borderRadius: '6px', border: '1px solid #3b82f6', background: '#eff6ff', color: '#1e40af', cursor: 'pointer' }}
+      >
+        Info Toast
+      </button>
+    </div>
+  );
+}
+
+// Wrapped demo with provider
+function ToastDemoWrapper() {
+  return (
+    <ToastProvider position="bottom-right" duration={5000}>
+      <ToastDemo />
+    </ToastProvider>
+  );
+}
+
+export default defineSegment({
+  component: Toast,
+
+  meta: {
+    name: 'Toast',
+    description: 'Brief, non-blocking notification messages',
+    category: 'feedback',
+    status: 'stable',
+    tags: ['notification', 'alert', 'message', 'feedback'],
+  },
+
+  usage: {
+    when: [
+      'Providing feedback after an action',
+      'Showing success/error status of operations',
+      'Non-critical information that doesn\'t require action',
+      'Temporary messages that auto-dismiss',
+    ],
+    whenNot: [
+      'Critical errors requiring user action (use Dialog)',
+      'Persistent information (use Alert)',
+      'Inline validation (use form error states)',
+      'System-wide announcements (use Banner)',
+    ],
+    guidelines: [
+      'Keep messages brief and actionable',
+      'Use appropriate variant for the message type',
+      'Auto-dismiss after reasonable duration (3-5s)',
+      'Allow manual dismissal for longer messages',
+      'Limit number of simultaneous toasts',
+    ],
+    accessibility: [
+      'Use role="alert" for important messages',
+      'Ensure sufficient display time for reading',
+      'Don\'t rely solely on color for meaning',
+      'Provide dismiss button with accessible label',
+    ],
+  },
+
+  props: {
+    title: {
+      type: 'string',
+      description: 'Toast title',
+    },
+    description: {
+      type: 'string',
+      description: 'Additional message content',
+    },
+    variant: {
+      type: 'enum',
+      values: ['default', 'success', 'error', 'warning', 'info'],
+      default: 'default',
+      description: 'Visual variant indicating message type',
+    },
+    duration: {
+      type: 'number',
+      default: 5000,
+      description: 'Auto-dismiss duration in ms (0 = no auto-dismiss)',
+    },
+    action: {
+      type: 'object',
+      description: 'Optional action button { label, onClick }',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Alert',
+      relationship: 'alternative',
+      note: 'Use Alert for persistent inline messages',
+    },
+    {
+      component: 'Dialog',
+      relationship: 'alternative',
+      note: 'Use Dialog for messages requiring user action',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'title: string - toast title',
+      'description: string - additional message',
+      'variant: default|success|error|warning|info',
+      'duration: number - ms before auto-dismiss',
+      'action: { label, onClick } - optional action',
+    ],
+    scenarioTags: [
+      'feedback.success',
+      'feedback.error',
+      'feedback.notification',
+    ],
+    a11yRules: [
+      'A11Y_ALERT_ROLE',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Interactive toast demo - click buttons to trigger toasts',
+      render: () => <ToastDemoWrapper />,
+    },
+    {
+      name: 'Success',
+      description: 'Success message variant',
+      render: () => (
+        <Toast
+          title="Success!"
+          description="Your changes have been saved."
+          variant="success"
+        />
+      ),
+    },
+    {
+      name: 'Error',
+      description: 'Error message variant',
+      render: () => (
+        <Toast
+          title="Error"
+          description="Failed to save changes. Please try again."
+          variant="error"
+        />
+      ),
+    },
+    {
+      name: 'Warning',
+      description: 'Warning message variant',
+      render: () => (
+        <Toast
+          title="Warning"
+          description="This action cannot be undone."
+          variant="warning"
+        />
+      ),
+    },
+    {
+      name: 'Info',
+      description: 'Informational message variant',
+      render: () => (
+        <Toast
+          title="New Update"
+          description="Version 2.0 is now available."
+          variant="info"
+        />
+      ),
+    },
+    {
+      name: 'With Action',
+      description: 'Toast with an action button',
+      render: () => (
+        <Toast
+          title="File deleted"
+          description="The file has been moved to trash."
+          action={{
+            label: 'Undo',
+            onClick: () => console.log('Undo clicked'),
+          }}
+        />
+      ),
+    },
+  ],
+});