@ossy/design-system 3.0.3 → 3.0.4

package/src/form/Form.jsx

@@ -0,0 +1,132 @@
+import React, { useCallback, useMemo, useState } from 'react'
+import { View } from '../view'
+import { Alert } from '../alert'
+import { applyFieldChange } from '../fields/applyFieldChange'
+import { FormContext } from './FormContext.jsx'
+
+function fieldNameFromTarget(target) {
+  if (!target) return null
+  if (typeof target.name === 'string' && target.name.length > 0) return target.name
+  if (typeof target.id === 'string' && target.id.length > 0 && !target.id.includes('.')) {
+    return target.id
+  }
+  return null
+}
+
+/**
+ * @typedef {object} FormChangeDetail
+ * @property {import('react').ChangeEvent} event Native change event (or synthetic field commit).
+ * @property {{ name: string, type?: string } | undefined} field Matching field def from `fields`.
+ * @property {unknown} value New value for that field after the change.
+ * @property {Record<string, unknown>} data Full form data after the change.
+ */
+
+/**
+ * @typedef {object} FormContextValue
+ * @property {string} id Stable form id for flow-runner (`form[id="…"]`).
+ * @property {string} [schemaId] Resource schema id for field copy keys (`{schemaId}.{fieldName}.label`).
+ * @property {{ name: string, type?: string, label?: string, required?: boolean, options?: string[], accept?: string, min?: number, max?: number }[]} fields
+ * @property {Record<string, unknown>} data Current field values.
+ * @property {(detail: FormChangeDetail) => void} onChange
+ * @property {readonly string[]} status
+ */
+
+/**
+ * Form provider + semantic `<form>`. Supports controlled (`data` + `onChange`) and
+ * uncontrolled (`defaultData`) modes. Uncontrolled updates use {@link applyFieldChange}.
+ *
+ * Pair with {@link FieldFactory} for template-driven fields. Place action buttons
+ * outside {@link FieldFactory} so they are not disabled by its fieldset.
+ *
+ * Submit handlers run only after native validation passes (`checkValidity()` on the form).
+ * When `validate` is set, it runs after native checks and can block submit.
+ *
+ * @param {{
+ *   id: string,
+ *   schemaId?: string,
+ *   fields: { name: string, type?: string, label?: string, required?: boolean, options?: string[], accept?: string, min?: number, max?: number }[],
+ *   data?: Record<string, unknown>,
+ *   defaultData?: Record<string, unknown>,
+ *   onChange?: (detail: FormChangeDetail) => void,
+ *   onSubmit?: (data: Record<string, unknown>, event: import('react').FormEvent<HTMLFormElement>) => void | Promise<void>,
+ *   validate?: (data: Record<string, unknown>) => { ok: true, data?: Record<string, unknown> } | { ok: false, message?: string },
+ *   status?: readonly string[],
+ *   children?: import('react').ReactNode,
+ * }} props
+ */
+export function Form ({
+  id,
+  schemaId,
+  fields,
+  data: dataProp,
+  defaultData,
+  onChange,
+  onSubmit,
+  validate,
+  status = [],
+  children,
+  ...props
+}) {
+  const [internalData, setInternalData] = useState(defaultData ?? {})
+  const [validationError, setValidationError] = useState()
+  const isControlled = dataProp !== undefined
+  const data = isControlled ? dataProp : internalData
+
+  const handleChange = useCallback((event) => {
+    setValidationError(undefined)
+    const nextData = applyFieldChange(data, event)
+    if (!isControlled) {
+      setInternalData(nextData)
+    }
+    const fieldName = fieldNameFromTarget(event?.target)
+    const field = fieldName ? fields.find(f => f.name === fieldName) : undefined
+    onChange?.({
+      event,
+      field,
+      value: fieldName ? nextData[fieldName] : undefined,
+      data: nextData,
+    })
+  }, [data, fields, isControlled, onChange])
+
+  const contextValue = useMemo(() => ({
+    id,
+    schemaId,
+    fields,
+    data,
+    onChange: handleChange,
+    status,
+  }), [id, schemaId, fields, data, handleChange, status])
+
+  return (
+    <FormContext.Provider value={contextValue}>
+      <View
+        as="form"
+        id={id}
+        onSubmit={e => {
+          e.preventDefault()
+          if (!onSubmit) return
+          if (!e.currentTarget.checkValidity()) return
+          let submitData = data
+          if (validate) {
+            const result = validate(data)
+            if (!result.ok) {
+              setValidationError(result.message ?? 'Validation failed')
+              return
+            }
+            submitData = result.data ?? data
+          }
+          setValidationError(undefined)
+          onSubmit(submitData, e)
+        }}
+        {...props}
+      >
+        {validationError ? (
+          <Alert variant="danger" style={{ marginBottom: 'var(--space-m)' }}>
+            {validationError}
+          </Alert>
+        ) : null}
+        {children}
+      </View>
+    </FormContext.Provider>
+  )
+}

package/src/form/Form.stories.jsx

@@ -0,0 +1,69 @@
+import React, { useState } from 'react'
+import { Button } from '../button/index.js'
+import { View } from '../view'
+import { Form, FieldFactory, FormStatus } from './index.js'
+
+const dataPreviewStyle = {
+  margin: 0,
+  padding: 'var(--space-s)',
+  background: 'var(--color-secondary)',
+  color: 'var(--text-default-color, CanvasText)',
+  borderRadius: 'var(--space-xs)',
+  border: '1px solid var(--separator-primary)',
+  fontSize: 12,
+  overflow: 'auto',
+}
+
+export default {
+  title: 'Design System/Forms/Form',
+  component: Form,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      story: {
+        inline: true,
+        height: 'auto',
+      },
+    },
+  },
+}
+
+const demoFields = [
+  { name: 'firstName', type: 'text', label: 'First name', required: true },
+  { name: 'lastName', type: 'text', label: 'Last name', required: true },
+  { name: 'email', type: 'email', label: 'Email', required: true },
+  { name: 'active', type: 'boolean', label: 'Active' },
+]
+
+function FormShell ({ status = [], initial = {} }) {
+  const [preview, setPreview] = useState(initial)
+  return (
+    <View
+      surface="primary"
+      inset="m"
+      roundness="m"
+      gap="m"
+      style={{ maxWidth: 480, fontFamily: 'system-ui, sans-serif' }}
+    >
+      <Form
+        id="@ossy/storybook/form/demo"
+        fields={demoFields}
+        defaultData={initial}
+        onChange={({ data }) => setPreview(data)}
+        onSubmit={data => setPreview(data)}
+        status={status}
+        gap="m"
+      >
+        <FieldFactory />
+        <Button type="submit" variant="cta">
+          Submit
+        </Button>
+      </Form>
+      <pre style={dataPreviewStyle}>{JSON.stringify(preview, null, 2)}</pre>
+    </View>
+  )
+}
+
+export const Default = () => <FormShell />
+
+export const Submitting = () => <FormShell status={[FormStatus.Submitting]} />

package/src/form/FormContext.jsx

@@ -0,0 +1,22 @@
+import React, { createContext, useContext } from 'react'
+
+/** @type {import('react').Context<import('./Form.jsx').FormContextValue | null>} */
+export const FormContext = createContext(null)
+
+/**
+ * @returns {import('./Form.jsx').FormContextValue | null}
+ */
+export function useOptionalFormContext () {
+  return useContext(FormContext)
+}
+
+/**
+ * @returns {import('./Form.jsx').FormContextValue}
+ */
+export function useFormContext () {
+  const ctx = useContext(FormContext)
+  if (!ctx) {
+    throw new Error('useFormContext must be used within a Form')
+  }
+  return ctx
+}

package/src/form/FormStatus.js

@@ -0,0 +1,6 @@
+/** Form lifecycle states — string values compatible with {@link AsyncStatus}. */
+export const FormStatus = {
+  Submitting: 'Submitting',
+  Loading: 'Loading',
+  Disabled: 'Disabled',
+}

package/src/form/index.js

@@ -0,0 +1,4 @@
+export { Form } from './Form.jsx'
+export { FieldFactory } from './FieldFactory.jsx'
+export { FormContext, useFormContext } from './FormContext.jsx'
+export { FormStatus } from './FormStatus.js'

package/src/guide/Guide.jsx

@@ -0,0 +1,43 @@
+import React from 'react'
+import { Text } from '../text'
+import { Button } from '../button'
+
+export const Guide = ({
+  title,
+  titleVariant = 'heading-secondary',
+  text,
+  textVariant,
+  textParams,
+  actions = [],
+  as: Element = 'div',
+  children,
+  align = 'center',
+  style = {},
+  ...props
+}) => (
+  <Element {...props} style={{ textAlign: align, ...style }}>
+    <style href="@ossy/design-system/guide" precedence='high'>
+    {`
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      text-align: center;
+    `}
+    </style>
+    <div>
+      {title && (
+        <Text as="h2" variant={titleVariant} text={title} style={{ marginBottom: 'var(--space-s)' }} />
+      )}
+      {
+        !!text
+          ? <Text variant={textVariant} text={text} params={textParams} style={{ marginBottom: 'var(--space-m)' }} />
+          : children
+      }
+      <div style={{ display: 'flex', gap: 'var(--space-m)', justifyContent: 'center' }}>
+        {actions.map(({ label, key, ...actionProps }) => (
+          <Button {...actionProps} key={key ?? label} label={label} />
+        ))}
+      </div>
+    </div>
+  </Element>
+)

package/src/guide/Guide.stories.jsx

@@ -0,0 +1,37 @@
+import React from 'react'
+import { Guide } from './Guide.jsx'
+
+export default {
+  title: 'Design System/Feedback/Guide',
+  component: Guide,
+}
+
+export const Default = {
+  args: {
+    title: 'Not Found',
+    text: 'We could not find what you were looking for',
+  },
+}
+
+export const WithActions = {
+  args: {
+    title: 'Not Found',
+    text: 'We could not find what you were looking for',
+    actions: [
+      { label: 'Click me!' },
+      { label: 'Click me!', variant: 'cta' },
+    ],
+  },
+}
+
+export const WithTitleVariantion = {
+  args: {
+    title: 'Not Found',
+    titleVariant: 'hero',
+    text: 'We could not find what you were looking for',
+    actions: [
+      { label: 'Click me!' },
+      { label: 'Click me!', variant: 'cta' },
+    ],
+  },
+}

package/src/guide/index.js

@@ -0,0 +1 @@
+export * from './Guide.jsx'

package/src/header-layout/HeaderLayout.jsx

@@ -0,0 +1,43 @@
+import React from 'react'
+import { View } from '../view'
+
+/**
+ * CSS grid layout for header slots: leading (title + near), far, description, children.
+ * Grid rules live on `View layout="header"`; row count follows which `[data-header-slot="…"]`
+ * nodes are present (`:has()` in View.jsx). Used by ContentHeader and AppHeader.
+ */
+export function HeaderLayout ({
+  componentName,
+
+  title,
+  near,
+  far,
+  description,
+  children,
+
+  inset,
+  gap = 's',
+  ...props
+}) {
+  const hasLeading = title != null || near != null
+
+  return (
+    <View
+      layout="header"
+      inset={inset}
+      gap={gap}
+      data-component={componentName}
+      {...props}
+    >
+      {hasLeading && (
+        <div data-header-slot="leading">
+          {title}
+          {near}
+        </div>
+      )}
+      {far != null && <div data-header-slot="far">{far}</div>}
+      {description != null && <div data-header-slot="description">{description}</div>}
+      {children != null && <div data-header-slot="children">{children}</div>}
+    </View>
+  )
+}

package/src/hooks/index.js

@@ -0,0 +1,6 @@
+export * from './useForceRerender';
+export * from './useClipboardCopy.js'
+export * from './useDocumentTitle.js'
+export * from './useInputValue.js'
+export * from './useIntersectionObserver';
+export * from './useTimeout.js'

package/src/hooks/useClipboardCopy.js

@@ -0,0 +1,26 @@
+const isSafariBrowser = () => {
+  // https://gist.github.com/michancio/10105690
+  const isChrome = navigator.userAgent.indexOf('Chrome') > -1
+  const isSafari = navigator.userAgent.indexOf('Safari') > -1
+
+    if (isSafari){
+        if (isChrome)  // Chrome seems to have both Chrome and Safari userAgents
+            return false;
+        else
+            return true;
+    }
+    return false;
+}
+
+export const useClipboardCopy = () => {
+  if (isSafariBrowser()) return [false, () => {}]
+  return [
+    true,
+    textToCopy => navigator.permissions.query({name: 'clipboard-write'})
+      .then(result => {
+        if (result.state === 'granted' || result.state === 'prompt') {
+          navigator.clipboard.writeText(textToCopy)
+        }
+      })
+    ]
+}

package/src/hooks/useDocumentTitle.js

@@ -0,0 +1,22 @@
+import { useEffect } from 'react'
+import { pageIdToDocumentTitleKey } from '@ossy/locale'
+import { useLocale } from '../locale/index.js'
+
+/**
+ * Set `document.title` from a literal string, translation key, or page id.
+ *
+ * @param {string} titleOrKey Document title or translation key when `options.key` is true
+ * @param {{ key?: boolean, pageId?: string }} [options]
+ */
+export const useDocumentTitle = (titleOrKey, options = {}) => {
+  const { t } = useLocale()
+  const title = options.pageId
+    ? t(pageIdToDocumentTitleKey(options.pageId))
+    : options.key
+      ? t(titleOrKey)
+      : titleOrKey
+
+  useEffect(() => {
+    document.title = title
+  }, [title])
+}

package/src/hooks/useForceRerender.js

@@ -0,0 +1,9 @@
+import { useState, useCallback } from 'react';
+
+export const useForceRerender = () => {
+  const [hasForcedRerender, setForcedRerender] = useState(0);
+  return [
+    hasForcedRerender,
+    useCallback(() => setForcedRerender(n => n + 1), [])
+  ];
+}

package/src/hooks/useInputValue.js

@@ -0,0 +1,23 @@
+import { useState } from 'react'
+
+export const useInputValue = (defaultValue = '') => {
+  const [value, setValue] = useState(defaultValue)
+
+  const setValueFromEvent = maybeEvent => {
+
+    if (typeof maybeEvent === 'string') {
+      setValue(maybeEvent)
+    } else if (!!event && !!event.target && !!event.target.value ) {
+      setValue(event.target.value)
+    } else {
+      setValue('')
+    }
+
+  }
+
+  return [
+    value,
+    setValueFromEvent,
+    () => setValue(defaultValue)
+  ]
+}

package/src/hooks/useInputValue.stories.jsx

@@ -0,0 +1,26 @@
+import React from 'react'
+import { useInputValue } from './useInputValue.js'
+
+function InputValueDemo () {
+  const [username, setUsername] = useInputValue()
+  return (
+    <>
+      <input
+        id="path"
+        type="text"
+        placeholder="Username"
+        value={username}
+        onChange={setUsername}
+      />
+      <span>your username is: {username}</span>
+    </>
+  )
+}
+
+export default {
+  title: 'Design System/Base/useInputValue',
+  component: useInputValue,
+  render: () => <InputValueDemo />,
+}
+
+export const Default = {}

package/src/hooks/useIntersectionObserver.js

@@ -0,0 +1,29 @@
+'use client'
+import { useEffect, useRef } from 'react';
+
+export const useIntersectionObserver = (
+  onNewObservation, // (entries, observer) => void,
+  options
+) => {
+
+  const observerRef = useRef(typeof IntersectionObserver !== 'undefined' && new IntersectionObserver(
+    onNewObservation,
+    options
+  ));
+
+  useEffect(() => {
+    const currentObserver = observerRef.current;
+    currentObserver.disconnect();
+
+    const newObserver = new IntersectionObserver(
+      onNewObservation,
+      options
+    );
+
+    return () => {
+      newObserver.disconnect();
+    }
+  }, [onNewObservation, options]);
+
+  return observerRef?.current;
+}

package/src/hooks/useTimeout.js

@@ -0,0 +1,24 @@
+import React, { useEffect, useRef } from 'react'
+
+// Taken from: https://felixgerschau.com/react-hooks-settimeout/#declarative-timeouts-with-the-usetimeout-hook
+export const useTimeout = (callback, delay) => {
+  const savedCallback = useRef(callback)
+
+  // Remember the latest callback if it changes.
+  useEffect(() => {
+    savedCallback.current = callback
+  }, [callback])
+
+  // Set up the timeout.
+  useEffect(() => {
+    // Don't schedule if no delay is specified.
+    if (delay === null) return
+
+    const id = setTimeout(
+      () => savedCallback.current(),
+      delay
+    )
+
+    return () => clearTimeout(id)
+  }, [delay])
+}