@graphprotocol/gds-react 0.1.1 → 0.2.0

package/src/hooks/useCSSPropsPolyfill.ts

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useRef, type Ref, type RefCallback } from 'react'
+import type { Ref, RefCallback } from 'react'
 
 import {
   getCSSPropRawValue,
@@ -9,7 +9,7 @@ import {
 } from '@graphprotocol/gds-css'
 
 import { useCSSProps, type PassedValues, type PropValues } from './useCSSProps.ts'
-import { useForceRerender } from './useForceRerender.ts'
+import { useFirstRender } from './useFirstRender.ts'
 
 type ExtractPolyfillValues<P extends CSSPropsConfig> = {
   [K in keyof P as P[K]['type'] extends 'values' ? K : never]: CSSPropType<P[K]> | undefined
@@ -68,19 +68,21 @@ export function useCSSPropsPolyfill<
   const allPassedValues = (() => {
     if (!returnPropValues) return passedValues
     if (returnPropValues === true) return passedValues
-    const merged = { ...passedValues }
-    for (const [key, value] of Object.entries(returnPropValues)) {
-      if (key in passedValues && passedValues[key as keyof typeof passedValues] !== value) {
+    const passed = passedValues as Record<string, unknown>
+    const merged = { ...passed }
+    for (const key of Object.keys(returnPropValues)) {
+      const value = returnPropValues[key]
+      if (key in passedValues && passed[key] !== value) {
         throw new Error(
-          `[useCSSPropsPolyfill] Conflicting values for prop \`${key}\`: ${passedValues[key as keyof typeof passedValues]} vs ${value}`,
+          `[useCSSPropsPolyfill] Conflicting values for prop \`${key}\`: ${String(passed[key])} vs ${value}`,
         )
       }
-      merged[key as keyof typeof merged] = value as (typeof merged)[keyof typeof merged]
+      merged[key] = value
     }
-    return merged
+    return merged as typeof passedValues
   })()
 
-  const [callbackRef, propValues, props] = useCSSProps(component, allPassedValues, {
+  const [callbackRef, propValues, cssProps] = useCSSProps(component, allPassedValues, {
     ref,
     disabled: !polyfillEnabled && !returnPropValues,
   })
@@ -92,30 +94,20 @@ export function useCSSPropsPolyfill<
    * to immediately rerender in browsers that support style queries); unfortunately, that would
    * cause a flash of missing styles in browsers that need the polyfill.
    */
-  const firstRender = useRef(true)
+  const firstRender = useFirstRender({ immediatelyRerender: !polyfillEnabled })
   const polyfillAttributes =
-    polyfillEnabled || firstRender.current
+    polyfillEnabled || firstRender
       ? Object.fromEntries(
-          props
+          cssProps
             .filter((prop) => prop.name in passedValues)
             .map((prop) => {
               const value = propValues[prop.name as keyof typeof propValues]
-              const rawValue = getCSSPropRawValue(prop.cssProp, value)
+              const rawValue = getCSSPropRawValue(prop, value)
               return [prop.polyfillAttribute, rawValue]
             }),
         )
       : {}
 
-  // If the polyfill is not needed, rerender to remove the polyfill attributes
-  const [rerender] = useForceRerender()
-  useLayoutEffect(() => {
-    firstRender.current = false
-    if (!polyfillEnabled) {
-      rerender()
-    }
-    // oxlint-disable-next-line exhaustive-deps
-  }, [])
-
   if (!returnPropValues) {
     return [callbackRef, polyfillAttributes] as const
   }

package/src/hooks/useCSSState.ts

@@ -56,15 +56,17 @@ export function useCSSState<
 
   const variables = useRefWithInit(() =>
     Object.keys(variableInitialValues).map((variableName) => {
-      const defaultValue =
-        variableName in cssStateVariables
-          ? cssStateVariables[variableName as CSSStateVariableName].defaultValue
-          : undefined
+      const isArbitrary = !(variableName in cssStateVariables)
+      const defaultValue = !isArbitrary
+        ? cssStateVariables[variableName as CSSStateVariableName].defaultValue
+        : undefined
       return {
         name: variableName,
         defaultValue,
         initialValue: variableInitialValues[variableName as keyof T] ?? defaultValue,
-        observedProperty: `--gds-observed-${variableName}`,
+        observedProperty: isArbitrary
+          ? `--gds-state-${variableName}`
+          : `--gds-observed-${variableName}`,
         exposedProperty: `--gds-exposed-${variableName}`,
         exposedAttribute: `data-gds-exposed-${variableName}`,
         polyfillAttribute: `data-gds-state-polyfill-${variableName}`,
@@ -105,7 +107,10 @@ export function useCSSState<
       for (const record of records) {
         if (propertyValues.get(record.property) !== record.value) {
           propertyValues.set(record.property, record.value)
-          if (record.property.startsWith('--gds-observed-')) {
+          if (
+            record.property.startsWith('--gds-state-') ||
+            record.property.startsWith('--gds-observed-')
+          ) {
             statePropertiesChanged = true
           }
         }

package/src/hooks/useEffectWithRefDeps.ts

@@ -20,7 +20,7 @@ export function useEffectWithRefDeps<T, RefDeps extends readonly Ref<T>[]>(
   effect: EffectCallback,
   regularDeps: unknown[],
   refDeps: [...RefDeps],
-  options: { deepCompare?: boolean; hook?: EffectHook } = {},
+  options: { deepCompare?: boolean | undefined; hook?: EffectHook | undefined } = {},
 ) {
   const { deepCompare = false, hook = useEffect } = options
 
@@ -53,7 +53,7 @@ export function useEffectWithRefDeps<T, RefDeps extends readonly Ref<T>[]>(
 
   const runEffectNextTick = useCallback(() => {
     const token = ++runEffectToken.current
-    queueMicrotask(() => {
+    window.queueMicrotask(() => {
       if (runEffectToken.current === token) {
         runEffect()
       }

package/src/hooks/useFirstRender.ts

@@ -0,0 +1,36 @@
+import { useEffect, useRef } from 'react'
+
+import { useForceRerender } from './useForceRerender.ts'
+
+interface UseFirstRenderOptions {
+  /** Callback to run on first render. */
+  callback?: () => void
+  /**
+   * If true, immediately triggers a re-render after the first render.
+   *
+   * @default false
+   */
+  immediatelyRerender?: boolean | undefined
+}
+
+export function useFirstRender(callback?: () => void): boolean
+export function useFirstRender(options: UseFirstRenderOptions): boolean
+export function useFirstRender(callbackOrOptions?: (() => void) | UseFirstRenderOptions) {
+  const options = typeof callbackOrOptions === 'function' ? undefined : callbackOrOptions
+  const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : options?.callback
+
+  const firstRender = useRef(true)
+  const [rerender] = useForceRerender()
+
+  useEffect(() => {
+    if (!firstRender.current) return
+    firstRender.current = false
+    callback?.()
+    if (options?.immediatelyRerender) {
+      rerender()
+    }
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return firstRender.current
+}

package/src/hooks/usePrevious.ts

@@ -12,10 +12,12 @@ const NOT_SET = Symbol('NOT_SET')
  *
  * @example
  *
- *     const previous = usePrevious(someValue)
- *     if (previous.hasChanged) {
- *       // Value changed from `previous.value` to `someValue`
- *     }
+ * ```ts
+ * const previous = usePrevious(someValue)
+ * if (previous.hasChanged) {
+ *   // Value changed from `previous.value` to `someValue`
+ * }
+ * ```
  */
 export function usePrevious<T>(value: T) {
   const previousRenderValueRef = useRef<T | typeof NOT_SET>(NOT_SET)

package/src/hooks/useRefWithInit.ts

@@ -1,4 +1,4 @@
-import { useRef, type MutableRefObject } from 'react'
+import { useRef, type RefObject } from 'react'
 
 /**
  * Works like `useRef` but accepts an initializer function that runs once on the first render, like
@@ -11,5 +11,5 @@ export function useRefWithInit<T>(initFn: () => T) {
     ref.current = initFn()
   }
 
-  return ref as MutableRefObject<T>
+  return ref as RefObject<T>
 }

package/src/hooks/useStyleObserver.ts

@@ -17,7 +17,11 @@ export function useStyleObserver<T extends string>(
   properties: T[],
   onChange: (records: Record<T>[]) => void,
   deps: unknown[],
-  options: { ref?: Ref<HTMLElement> | undefined; immediate?: boolean; disabled?: boolean } = {},
+  options: {
+    ref?: Ref<HTMLElement> | undefined
+    immediate?: boolean | undefined
+    disabled?: boolean | undefined
+  } = {},
 ) {
   const { ref: passedRef, immediate = false, disabled = false } = options
   const elementRef = useRef<HTMLElement>(null)

package/src/icons/CalendarDynamicIcon.tsx

@@ -2,17 +2,21 @@ import { useId } from 'react'
 
 import { Icon, type IconProps } from '../components/Icon.tsx'
 
-export interface CalendarDynamicIconProps extends IconProps {
+export interface CalendarDynamicIconProps extends Omit<IconProps, 'alt'> {
+  /** Defaults to a formatted version of `date`. */
+  alt?: string
   /**
-   * Day of the month.
+   * Day of the month, or a full date. If the latter, the icon will only display the day part, but
+   * the default `alt` will be the full formatted date.
    *
-   * @default new Date().getDate()
+   * @default new Date()
    */
-  date?: number
+  date?: number | Date
 }
 
 export function CalendarDynamicIcon({
-  date = new Date().getDate(),
+  alt,
+  date = new Date(),
   ...props
 }: CalendarDynamicIconProps) {
   const uniqueId = useId()
@@ -37,13 +41,19 @@ export function CalendarDynamicIcon({
                 fontSize="7px"
                 fontWeight="bold"
               >
-                {date}
+                {typeof date === 'number' ? date : date.getDate()}
               </text>
             </mask>
           </defs>
           <use href={`#${uniqueId}-calendar-path`} mask={`url(#${uniqueId}-text-mask)`} />
         </svg>
       }
+      alt={
+        alt ??
+        (typeof date === 'number'
+          ? `Day ${date} of the month`
+          : date.toLocaleDateString(undefined, { dateStyle: 'long' }))
+      }
       data-name="CalendarDynamic"
       {...props}
     />

package/src/icons/CopyInteractiveIcon.tsx

@@ -1,14 +1,19 @@
 import { useId } from 'react'
-import type { SetOptional } from 'type-fest'
 
 import { Icon, type IconProps } from '../components/Icon.tsx'
 
-export interface CopyInteractiveIconProps extends SetOptional<IconProps, 'alt'> {
+export interface CopyInteractiveIconProps extends Omit<IconProps, 'alt'> {
+  /** @default 'Copy' */
+  alt?: IconProps['alt']
   /** @default false */
-  copied?: boolean
+  copied?: boolean | undefined
 }
 
-export function CopyInteractiveIcon({ copied = false, ...props }: CopyInteractiveIconProps) {
+export function CopyInteractiveIcon({
+  alt = 'Copy',
+  copied = false,
+  ...props
+}: CopyInteractiveIconProps) {
   const uniqueId = useId()
 
   return (
@@ -85,7 +90,7 @@ export function CopyInteractiveIcon({ copied = false, ...props }: CopyInteractiv
           </g>
         </svg>
       }
-      alt="Copy"
+      alt={alt}
       data-name="CopyAnimated"
       {...props}
     />

package/src/icons/SidebarLeftInteractiveIcon.tsx

@@ -1,10 +1,14 @@
-import type { SetOptional } from 'type-fest'
-
 import { Icon, type IconProps } from '../components/Icon.tsx'
 
-export interface SidebarLeftInteractiveIconProps extends SetOptional<IconProps, 'alt'> {}
+export interface SidebarLeftInteractiveIconProps extends Omit<IconProps, 'alt'> {
+  /** @default 'Toggle sidebar' */
+  alt?: IconProps['alt']
+}
 
-export function SidebarLeftInteractiveIcon(props: SidebarLeftInteractiveIconProps) {
+export function SidebarLeftInteractiveIcon({
+  alt = 'Toggle sidebar',
+  ...props
+}: SidebarLeftInteractiveIconProps) {
   return (
     <Icon
       src={
@@ -19,7 +23,7 @@ export function SidebarLeftInteractiveIcon(props: SidebarLeftInteractiveIconProp
           />
         </svg>
       }
-      alt=""
+      alt={alt}
       data-name="SidebarLeftInteractive"
       {...props}
     />

package/src/icons/SidebarRightInteractiveIcon.tsx

@@ -1,10 +1,14 @@
-import type { SetOptional } from 'type-fest'
-
 import { Icon, type IconProps } from '../components/Icon.tsx'
 
-export interface SidebarRightInteractiveIconProps extends SetOptional<IconProps, 'alt'> {}
+export interface SidebarRightInteractiveIconProps extends Omit<IconProps, 'alt'> {
+  /** @default 'Toggle sidebar' */
+  alt?: IconProps['alt']
+}
 
-export function SidebarRightInteractiveIcon(props: SidebarRightInteractiveIconProps) {
+export function SidebarRightInteractiveIcon({
+  alt = 'Toggle sidebar',
+  ...props
+}: SidebarRightInteractiveIconProps) {
   return (
     <Icon
       src={
@@ -19,7 +23,7 @@ export function SidebarRightInteractiveIcon(props: SidebarRightInteractiveIconPr
           />
         </svg>
       }
-      alt=""
+      alt={alt}
       data-name="SidebarRightInteractive"
       {...props}
     />

package/src/tailwind-plugin.ts

@@ -7,7 +7,6 @@ import { AddressMeta } from './components/Address.meta.ts'
 import { AvatarMeta } from './components/Avatar.meta.ts'
 import { AvatarGroupMeta } from './components/AvatarGroup.meta.ts'
 import { AddonMeta } from './components/base/Addon.meta.ts'
-import { ButtonOrLinkMeta } from './components/base/ButtonOrLink.meta.ts'
 import { CheckableMeta } from './components/base/Checkable.meta.ts'
 import { FieldMeta } from './components/base/Field.meta.ts'
 import { TransitionMeta } from './components/base/Transition.meta.ts'
@@ -16,8 +15,10 @@ import { ButtonMeta } from './components/Button.meta.ts'
 import { ButtonGroupMeta } from './components/ButtonGroup.meta.ts'
 import { CardMeta } from './components/Card.meta.ts'
 import { CheckboxMeta } from './components/Checkbox.meta.ts'
+import { ChipGroupMeta, ChipMeta } from './components/Chip.meta.ts'
 import { ClusterMeta } from './components/Cluster.meta.ts'
 import { CodeBlockMeta, CodeBlockTabsMeta } from './components/CodeBlock.meta.ts'
+import { CodeInlineMeta } from './components/CodeInline.meta.ts'
 import { CopyButtonMeta } from './components/CopyButton.meta.ts'
 import { CurrencyInputMeta } from './components/CurrencyInput.meta.ts'
 import { DescriptionListItemMeta, DescriptionListMeta } from './components/DescriptionList.meta.ts'
@@ -77,15 +78,17 @@ const gdsTailwindPluginWithComponents: ReturnType<typeof createPlugin> = createP
     AvatarGroupMeta,
     BreadcrumbsItemMeta,
     BreadcrumbsMeta,
-    ButtonOrLinkMeta,
     ButtonMeta,
     ButtonGroupMeta,
     CardMeta,
-    CodeBlockMeta,
-    CodeBlockTabsMeta,
     CheckableMeta,
     CheckboxMeta,
+    ChipMeta,
+    ChipGroupMeta,
     ClusterMeta,
+    CodeBlockMeta,
+    CodeBlockTabsMeta,
+    CodeInlineMeta,
     CopyButtonMeta,
     CurrencyInputMeta,
     DescriptionListItemMeta,
@@ -108,8 +111,8 @@ const gdsTailwindPluginWithComponents: ReturnType<typeof createPlugin> = createP
     StatusMeta,
     StepperMeta,
     SwitchMeta,
-    TabSetTabsMeta,
     TabSetTabMeta,
+    TabSetTabsMeta,
     TagMeta,
     TextAreaMeta,
     ToggleButtonMeta,

package/src/utils/cn.ts

@@ -3,7 +3,9 @@
  *
  * @example
  *
- *     cn('base-class', condition && 'conditional-class', className)
+ * ```ts
+ * cn('base-class', condition && 'conditional-class', className)
+ * ```
  */
 export function cn(...classes: (string | undefined | null | false)[]): string {
   return classes.filter(Boolean).join(' ')

package/src/utils/getCSSPropsAttributes.ts

@@ -12,8 +12,14 @@ type AllCSSProps<C extends GDSComponent> = {
   [K in keyof ComponentCSSProps<C>]-?: ComponentCSSProps<C>[K] | undefined
 }
 
-// For props with a `defaultValue`, ensure they can be `undefined` (preventing destructuring defaults like `{ size = 'medium' }`).
-// For props without a `defaultValue`, allow any value since they're required and will never be `undefined`.
+/**
+ * Validates the passed values object:
+ *
+ * - Rejects keys that are not CSS props.
+ * - For props with a `defaultValue`, ensures they can be `undefined` (preventing destructuring
+ *   defaults, which would break `default-*` utilities).
+ * - For props without a `defaultValue`, allows any value since they're required.
+ */
 type ValidatePassedValues<C extends GDSComponent, T extends AllCSSProps<C>> = {
   [K in keyof T]: K extends keyof ComponentCSSPropsConfig<C>
     ? 'defaultValue' extends keyof ComponentCSSPropsConfig<C>[K]
@@ -21,12 +27,11 @@ type ValidatePassedValues<C extends GDSComponent, T extends AllCSSProps<C>> = {
         ? T[K]
         : never
       : T[K]
-    : T[K]
+    : `"${K & string}" is not a CSS prop of this component`
 }
 
 /**
- * Returns attributes to spread on the root element of a component that supports CSS Props. This
- * enables the CSS Props system to apply prop-based styling.
+ * Returns attributes to spread on the root element of a component that supports CSS props.
  *
  * @param component The component metadata object created with createComponent.
  * @param passedValues Object containing all the CSS prop values from the component props.
@@ -41,13 +46,13 @@ export function getCSSPropsAttributes<C extends GDSComponent, V extends AllCSSPr
   const customProperties: Record<string, string> = {}
 
   for (const propName in passedValues) {
-    const prop = component.getCSSPropByName(propName)
+    const cssProp = component.getCSSPropByName(propName)
     const value = passedValues[propName]
     if (value === undefined) continue
-    customProperties[`--gds-passed-${prop.kebabName}`] = getCSSPropRawValue(prop, value)
+    customProperties[`--gds-passed-${cssProp.kebabName}`] = getCSSPropRawValue(cssProp, value)
   }
 
   return {
-    style: { ...style, ...customProperties },
+    style: { ...customProperties, ...style },
   }
 }

package/src/utils/splitProps.ts

@@ -10,28 +10,22 @@
  * destructured), `style`, `inert`, `hidden`, and `aria-hidden` go in `rootProps`, along with data
  * attributes, since they can be coupled to the `className` to apply styles conditionally, e.g.
  * `<Button data-highlighted={highlighted} className="data-[highlighted]:prop-variant-primary" />`.
- * However, data attributes can also be needed on the underlying element in some cases, so they are
- * also included in the `nestedProps`, except the ones starting with `data-gds-`, to avoid messing
- * with the CSS props or states systems.
  */
 export function splitProps<T extends Record<string, unknown>>(props: T) {
   const rootProps: Record<string, unknown> = {}
   const nestedProps: Record<string, unknown> = {}
 
   for (const [key, value] of Object.entries(props)) {
-    const isDataAttribute = key.startsWith('data-')
-    const isGDSDataAttribute = key.startsWith('data-gds-')
     const isRootProp =
       key === 'className' ||
       key === 'style' ||
       key === 'inert' ||
       key === 'hidden' ||
       key === 'aria-hidden' ||
-      isDataAttribute
+      key.startsWith('data-')
     if (isRootProp) {
       rootProps[key] = value
-    }
-    if (!isRootProp || (isDataAttribute && !isGDSDataAttribute)) {
+    } else {
       nestedProps[key] = value
     }
   }
@@ -49,7 +43,13 @@ export function splitProps<T extends Record<string, unknown>>(props: T) {
         : never]: T[K]
     }
     nestedProps: {
-      [K in keyof T as K extends 'className' | 'style' | 'inert' | 'hidden' | 'aria-hidden'
+      [K in keyof T as K extends
+        | 'className'
+        | 'style'
+        | 'inert'
+        | 'hidden'
+        | 'aria-hidden'
+        | `data-${string}`
         ? never
         : K]: T[K]
     }

package/src/utils/trimReactNode.tsx

@@ -12,14 +12,16 @@ import { Children, isValidElement, type ReactElement, type ReactNode } from 'rea
  *
  * @example
  *
- *     trimReactNode('  hello  ') // 'hello'
- *     trimReactNode(
- *       <>
- *         {' '}
- *         <span>test</span>{' '}
- *       </>,
- *     ) // <><span>test</span></>
- *     trimReactNode([' ', <div>content</div>, ' ']) // [<div>content</div>]
+ * ```tsx
+ * trimReactNode('  hello  ') // 'hello'
+ * trimReactNode(
+ *   <>
+ *     {' '}
+ *     <span>test</span>{' '}
+ *   </>,
+ * ) // <><span>test</span></>
+ * trimReactNode([' ', <div>content</div>, ' ']) // [<div>content</div>]
+ * ```
  *
  * @param node - The `ReactNode` to trim.
  * @returns A new `ReactNode` with leading and trailing whitespace removed.

package/dist/components/base/ButtonOrLink.meta.d.ts

@@ -1,2 +0,0 @@
-export declare const ButtonOrLinkMeta: import("@graphprotocol/gds-css").GDSComponent<import("@graphprotocol/gds-css").CSSPropsConfig, boolean>;
-//# sourceMappingURL=ButtonOrLink.meta.d.ts.map

package/dist/components/base/ButtonOrLink.meta.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ButtonOrLink.meta.d.ts","sourceRoot":"","sources":["../../../src/components/base/ButtonOrLink.meta.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,yGAE3B,CAAA"}

package/dist/components/base/ButtonOrLink.meta.js

@@ -1,6 +0,0 @@
-import { createComponent } from '@graphprotocol/gds-css';
-// `ButtonOrLink` doesn't use CSS Props, but we register it for the `*-button-or-link` variants
-export const ButtonOrLinkMeta = createComponent('ButtonOrLink', {
-    containerName: null,
-});
-//# sourceMappingURL=ButtonOrLink.meta.js.map

package/dist/components/base/ButtonOrLink.meta.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ButtonOrLink.meta.js","sourceRoot":"","sources":["../../../src/components/base/ButtonOrLink.meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAC,cAAc,EAAE;IAC9D,aAAa,EAAE,IAAI;CACpB,CAAC,CAAA"}

package/src/components/base/ButtonOrLink.meta.ts

@@ -1,6 +0,0 @@
-import { createComponent } from '@graphprotocol/gds-css'
-
-// `ButtonOrLink` doesn't use CSS Props, but we register it for the `*-button-or-link` variants
-export const ButtonOrLinkMeta = createComponent('ButtonOrLink', {
-  containerName: null,
-})