@uniformdev/design-system 20.50.1-alpha.1 → 20.50.1-alpha.16

package/README.md

@@ -55,7 +55,59 @@ export default function Document() {
 }
 ```
 
-### 2. Use Components
+### 2. Set up Providers (as needed)
+
+Some components rely on React context providers to function correctly. Set them up as needed:
+
+#### IconsProvider
+
+Required by the `Icon` component when using string-based icon names (e.g. `icon="mail"`). Without the provider, you can still pass icon components directly.
+
+```tsx
+import { IconsProvider, Icon } from '@uniformdev/design-system';
+
+function App() {
+  return (
+    <IconsProvider>
+      <Icon icon="mail" />
+    </IconsProvider>
+  );
+}
+```
+
+**Direct consumers:** `Icon`
+**Indirect consumers:** Any component that renders an `Icon` internally (e.g. `Button`, `Callout`, `Details`, `Menu`, and many more)
+
+#### DrawerProvider
+
+Optional for basic `Drawer` usage -- `Drawer` creates its own internal provider and renderer when no external `DrawerProvider` is present. An explicit `DrawerProvider` is only needed for shared drawer stacks (e.g. multiple drawers rendering into the same `DrawerRenderer`).
+
+Required by `DrawerRenderer` and `TakeoverDrawerRenderer`, which must be rendered inside a `DrawerProvider`.
+
+```tsx
+import { DrawerProvider, Drawer, DrawerRenderer } from '@uniformdev/design-system';
+
+function App() {
+  return (
+    <DrawerProvider>
+      <Drawer id="my-drawer" header="Title">Content</Drawer>
+      <DrawerRenderer stackId="_default" />
+    </DrawerProvider>
+  );
+}
+```
+
+**Required by:** `DrawerRenderer`, `TakeoverDrawerRenderer`
+**Optional for:** `Drawer` (self-sufficient for simple cases)
+
+#### ParameterShell
+
+Only required when using `*Inner` components directly (e.g. `ParameterInputInner`, `ParameterSelectInner`). The outer wrapper components (`ParameterInput`, `ParameterSelect`, etc.) create a `ParameterShell` automatically, so no external setup is needed for typical usage.
+
+**Required by:** `ParameterInputInner`, `ParameterSelectInner`, `ParameterLinkInner`, `ParameterSelectSliderInner`, `ParameterToggleInner`, `ParameterNumberSliderInner`, `ParameterMultiSelectInner`, `ParameterTextareaInner`, `ParameterImageInner`
+**Not required by:** `ParameterInput`, `ParameterSelect`, `ParameterLink`, and other outer wrappers (they provide it internally)
+
+### 3. Use Components
 
 ```tsx
 import { Button, Heading, Card, Input } from '@uniformdev/design-system';

package/dist/index.d.mts

@@ -1348,6 +1348,7 @@ interface IconProps extends IconBaseProps {
 
 /**
  * Component that renders icons
+ * @requires IconsProvider - Wrap a parent component with `<IconsProvider>` for string-based icon names.
  * @example <Icon icon="add-r" iconColor="currentColor" />
  */
 declare const Icon: React__default.MemoExoticComponent<({ icon, iconColor, size, ...otherProps }: IconProps) => _emotion_react_jsx_runtime.JSX.Element | null>;
@@ -1905,6 +1906,7 @@ interface DrawerRendererProps extends Omit<React__default.HTMLAttributes<HTMLDiv
 }
 /**
  * Renders a stack of drawers in a different location than their original position in the component tree. Uses React Portal under the hood.
+ * @requires DrawerProvider - Must be rendered inside a `<DrawerProvider>`.
  * @example <DrawerProvider><Drawer id="my-drawer" stackId="my-stack" header="Title">Hello</Drawer><DrawerRenderer stackId="my-stack"/></DrawerProvider>
  */
 declare const DrawerRenderer: ({ stackId, position, width, minWidth, maxWidth, leftAligned, withoutFluidWidth, ...otherProps }: DrawerRendererProps) => _emotion_react_jsx_runtime.JSX.Element | null;
@@ -1994,8 +1996,10 @@ declare const useCurrentDrawer: () => {
     leftAligned?: DrawerRendererProps["leftAligned"];
 };
 /**
- * A drawer component that opens from the right side of is parent. The component is used in combination with DrawerProvider and DrawerRenderer
- * @example <Drawer id="my-drawer" header="Title">Hello</Drawer>
+ * A drawer component that opens from the right side of its parent.
+ * When used without an external `<DrawerProvider>`, creates its own provider and renderer internally.
+ * For shared drawer stacks, wrap with `<DrawerProvider>` and use a `<DrawerRenderer>`.
+ * @example <DrawerProvider><Drawer id="my-drawer" header="Title">Hello</Drawer><DrawerRenderer /></DrawerProvider>
  */
 declare const Drawer: React__default.ForwardRefExoticComponent<DrawerItem & Omit<DrawerRendererProps, "stackId"> & {
     header?: React__default.ReactNode;
@@ -2012,6 +2016,11 @@ type DrawerContentProps = {
 declare const DrawerContent: ({ children, buttonGroup, noPadding, ...props }: DrawerContentProps) => _emotion_react_jsx_runtime.JSX.Element;
 
 declare const TAKEOVER_STACK_ID = "takeover-stack";
+/**
+ * A specialized drawer renderer that takes over the full stack.
+ * @requires DrawerProvider - Must be rendered inside a `<DrawerProvider>`.
+ * @example <DrawerProvider><TakeoverDrawerRenderer /><Drawer id="my-drawer" header="Title">Hello</Drawer></DrawerProvider>
+ */
 declare const TakeoverDrawerRenderer: (props: Omit<DrawerRendererProps, "stackId"> & {
     stackId?: string;
 }) => _emotion_react_jsx_runtime.JSX.Element;
@@ -3430,13 +3439,14 @@ type ParameterImageProps = Omit<CommonParameterInputProps, 'inputIcon' | 'type'>
     /** Turns off the image preview, if it's not desired or rendered separately with `ParameterImageImage` elsewhere */
     disablePreview?: boolean;
 };
-/** @Example <ParameterImage {...inputArgs} value={value} onChange={(e) => setValue(e.currentTarget.value)} /> */
+/** @example <ParameterImage {...inputArgs} value={value} onChange={(e) => setValue(e.currentTarget.value)} /> */
 declare const ParameterImage: React__default.ForwardRefExoticComponent<Omit<CommonParameterInputProps, "type" | "inputIcon"> & React__default.InputHTMLAttributes<HTMLInputElement> & {
     /** Turns off the image preview, if it's not desired or rendered separately with `ParameterImageImage` elsewhere */
     disablePreview?: boolean;
 } & {
     children?: React__default.ReactNode | undefined;
 } & React__default.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterImageInner: React__default.ForwardRefExoticComponent<React__default.InputHTMLAttributes<HTMLInputElement> & {
     disablePreview?: boolean;
 } & React__default.RefAttributes<HTMLInputElement>>;
@@ -3469,6 +3479,7 @@ declare const ParameterInput: React$1.ForwardRefExoticComponent<CommonParameterP
      */
     enableMouseWheel?: boolean;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterInputInner: React$1.ForwardRefExoticComponent<React$1.InputHTMLAttributes<HTMLInputElement> & {
     enableMouseWheel?: boolean;
 } & React$1.RefAttributes<HTMLInputElement>>;
@@ -3515,6 +3526,7 @@ declare const ParameterLink: React$1.ForwardRefExoticComponent<CommonParameterPr
     disabled?: boolean;
     externalLink?: string;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterLinkInner: React$1.ForwardRefExoticComponent<Omit<ParameterLinkProps, "label" | "id"> & React$1.RefAttributes<HTMLInputElement>>;
 
 type ParameterMenuButtonProps = {
@@ -3535,11 +3547,14 @@ type ParameterMultiSelectProps = CommonParameterInputProps & ParameterMultiSelec
 };
 /**
  * @deprecated beta
- * @example <ParameterMultiSelect label="my label" id="my-id" options={[{ label: 'option label', value: 0}]} */
+ * @example <ParameterMultiSelect label="my label" id="my-id" options={[{ label: 'option label', value: 0}]}
+ */
 declare const ParameterMultiSelect: ({ disabled, ...props }: ParameterMultiSelectProps) => _emotion_react_jsx_runtime.JSX.Element;
 /**
  * @deprecated beta
- * @example  <ParameterMultiSelectInner options={[{ label: 'option label', value: 0}]} />*/
+ * @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component.
+ * @example <ParameterMultiSelectInner options={[{ label: 'option label', value: 0}]} />
+ */
 declare const ParameterMultiSelectInner: (props: ParameterMultiSelectInnerProps) => _emotion_react_jsx_runtime.JSX.Element;
 
 type ParameterNameAndPublicIdInputProps = {
@@ -3651,6 +3666,7 @@ declare const ParameterNumberSlider: React$1.ForwardRefExoticComponent<CommonPar
     captionTestId?: string;
     title?: string;
 } & Omit<SliderProps, "id" | "aria-label" | "options"> & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterNumberSliderInner: React$1.ForwardRefExoticComponent<Omit<SliderProps, "id" | "aria-label" | "options"> & React$1.RefAttributes<HTMLInputElement>>;
 
 type LinkNodeProps = NonNullable<LinkParamValue>;
@@ -3783,7 +3799,10 @@ declare const ParameterSelect: React$1.ForwardRefExoticComponent<CommonParameter
     captionTestId?: string;
     title?: string;
 } & CommonParameterSelectProps & React$1.InputHTMLAttributes<HTMLSelectElement> & React$1.RefAttributes<HTMLSelectElement>>;
-/** @example  <ParameterSelectInner options={[{ label: 'option label', value: 0}]} />*/
+/**
+ * @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component.
+ * @example <ParameterSelectInner options={[{ label: 'option label', value: 0}]} />
+ */
 declare const ParameterSelectInner: React$1.ForwardRefExoticComponent<Omit<ParameterSelectProps, "label" | "id"> & React$1.RefAttributes<HTMLSelectElement>>;
 
 type ParameterSelectSliderProps = CommonParameterInputProps & Omit<SliderProps, 'id' | 'aria-label' | 'value' | 'onChange' | 'min' | 'max' | 'step' | 'showNumberInput'> & {
@@ -3825,6 +3844,7 @@ declare const ParameterSelectSlider: React$1.ForwardRefExoticComponent<CommonPar
      */
     onChange: (value: string | undefined) => void;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterSelectSliderInner: React$1.ForwardRefExoticComponent<Omit<ParameterSelectSliderProps, "caption" | "title" | "errorTestId" | "captionTestId" | "menuItems" | "actionItems" | keyof CommonParameterProps> & React$1.RefAttributes<HTMLInputElement>>;
 
 /** A function that extracts all common props and element props
@@ -3892,7 +3912,10 @@ declare const ParameterTextarea: React$1.ForwardRefExoticComponent<CommonParamet
     captionTestId?: string;
     title?: string;
 } & React$1.TextareaHTMLAttributes<HTMLTextAreaElement> & React$1.RefAttributes<HTMLTextAreaElement>>;
-/** @example <ParameterTextareaInner /> */
+/**
+ * @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component.
+ * @example <ParameterTextareaInner />
+ */
 declare const ParameterTextareaInner: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLTextAreaElement> & React$1.RefAttributes<HTMLTextAreaElement>>;
 
 type ParameterToggleInnerProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> & {
@@ -3912,6 +3935,7 @@ declare const ParameterToggle: React$1.ForwardRefExoticComponent<CommonParameter
     type: "checkbox" | "radio";
     withoutIndeterminateState?: boolean;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterToggleInner: React$1.ForwardRefExoticComponent<Omit<React$1.InputHTMLAttributes<HTMLInputElement>, "type"> & {
     type: "checkbox" | "radio";
     withoutIndeterminateState?: boolean;

package/dist/index.d.ts

@@ -1348,6 +1348,7 @@ interface IconProps extends IconBaseProps {
 
 /**
  * Component that renders icons
+ * @requires IconsProvider - Wrap a parent component with `<IconsProvider>` for string-based icon names.
  * @example <Icon icon="add-r" iconColor="currentColor" />
  */
 declare const Icon: React__default.MemoExoticComponent<({ icon, iconColor, size, ...otherProps }: IconProps) => _emotion_react_jsx_runtime.JSX.Element | null>;
@@ -1905,6 +1906,7 @@ interface DrawerRendererProps extends Omit<React__default.HTMLAttributes<HTMLDiv
 }
 /**
  * Renders a stack of drawers in a different location than their original position in the component tree. Uses React Portal under the hood.
+ * @requires DrawerProvider - Must be rendered inside a `<DrawerProvider>`.
  * @example <DrawerProvider><Drawer id="my-drawer" stackId="my-stack" header="Title">Hello</Drawer><DrawerRenderer stackId="my-stack"/></DrawerProvider>
  */
 declare const DrawerRenderer: ({ stackId, position, width, minWidth, maxWidth, leftAligned, withoutFluidWidth, ...otherProps }: DrawerRendererProps) => _emotion_react_jsx_runtime.JSX.Element | null;
@@ -1994,8 +1996,10 @@ declare const useCurrentDrawer: () => {
     leftAligned?: DrawerRendererProps["leftAligned"];
 };
 /**
- * A drawer component that opens from the right side of is parent. The component is used in combination with DrawerProvider and DrawerRenderer
- * @example <Drawer id="my-drawer" header="Title">Hello</Drawer>
+ * A drawer component that opens from the right side of its parent.
+ * When used without an external `<DrawerProvider>`, creates its own provider and renderer internally.
+ * For shared drawer stacks, wrap with `<DrawerProvider>` and use a `<DrawerRenderer>`.
+ * @example <DrawerProvider><Drawer id="my-drawer" header="Title">Hello</Drawer><DrawerRenderer /></DrawerProvider>
  */
 declare const Drawer: React__default.ForwardRefExoticComponent<DrawerItem & Omit<DrawerRendererProps, "stackId"> & {
     header?: React__default.ReactNode;
@@ -2012,6 +2016,11 @@ type DrawerContentProps = {
 declare const DrawerContent: ({ children, buttonGroup, noPadding, ...props }: DrawerContentProps) => _emotion_react_jsx_runtime.JSX.Element;
 
 declare const TAKEOVER_STACK_ID = "takeover-stack";
+/**
+ * A specialized drawer renderer that takes over the full stack.
+ * @requires DrawerProvider - Must be rendered inside a `<DrawerProvider>`.
+ * @example <DrawerProvider><TakeoverDrawerRenderer /><Drawer id="my-drawer" header="Title">Hello</Drawer></DrawerProvider>
+ */
 declare const TakeoverDrawerRenderer: (props: Omit<DrawerRendererProps, "stackId"> & {
     stackId?: string;
 }) => _emotion_react_jsx_runtime.JSX.Element;
@@ -3430,13 +3439,14 @@ type ParameterImageProps = Omit<CommonParameterInputProps, 'inputIcon' | 'type'>
     /** Turns off the image preview, if it's not desired or rendered separately with `ParameterImageImage` elsewhere */
     disablePreview?: boolean;
 };
-/** @Example <ParameterImage {...inputArgs} value={value} onChange={(e) => setValue(e.currentTarget.value)} /> */
+/** @example <ParameterImage {...inputArgs} value={value} onChange={(e) => setValue(e.currentTarget.value)} /> */
 declare const ParameterImage: React__default.ForwardRefExoticComponent<Omit<CommonParameterInputProps, "type" | "inputIcon"> & React__default.InputHTMLAttributes<HTMLInputElement> & {
     /** Turns off the image preview, if it's not desired or rendered separately with `ParameterImageImage` elsewhere */
     disablePreview?: boolean;
 } & {
     children?: React__default.ReactNode | undefined;
 } & React__default.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterImageInner: React__default.ForwardRefExoticComponent<React__default.InputHTMLAttributes<HTMLInputElement> & {
     disablePreview?: boolean;
 } & React__default.RefAttributes<HTMLInputElement>>;
@@ -3469,6 +3479,7 @@ declare const ParameterInput: React$1.ForwardRefExoticComponent<CommonParameterP
      */
     enableMouseWheel?: boolean;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterInputInner: React$1.ForwardRefExoticComponent<React$1.InputHTMLAttributes<HTMLInputElement> & {
     enableMouseWheel?: boolean;
 } & React$1.RefAttributes<HTMLInputElement>>;
@@ -3515,6 +3526,7 @@ declare const ParameterLink: React$1.ForwardRefExoticComponent<CommonParameterPr
     disabled?: boolean;
     externalLink?: string;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterLinkInner: React$1.ForwardRefExoticComponent<Omit<ParameterLinkProps, "label" | "id"> & React$1.RefAttributes<HTMLInputElement>>;
 
 type ParameterMenuButtonProps = {
@@ -3535,11 +3547,14 @@ type ParameterMultiSelectProps = CommonParameterInputProps & ParameterMultiSelec
 };
 /**
  * @deprecated beta
- * @example <ParameterMultiSelect label="my label" id="my-id" options={[{ label: 'option label', value: 0}]} */
+ * @example <ParameterMultiSelect label="my label" id="my-id" options={[{ label: 'option label', value: 0}]}
+ */
 declare const ParameterMultiSelect: ({ disabled, ...props }: ParameterMultiSelectProps) => _emotion_react_jsx_runtime.JSX.Element;
 /**
  * @deprecated beta
- * @example  <ParameterMultiSelectInner options={[{ label: 'option label', value: 0}]} />*/
+ * @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component.
+ * @example <ParameterMultiSelectInner options={[{ label: 'option label', value: 0}]} />
+ */
 declare const ParameterMultiSelectInner: (props: ParameterMultiSelectInnerProps) => _emotion_react_jsx_runtime.JSX.Element;
 
 type ParameterNameAndPublicIdInputProps = {
@@ -3651,6 +3666,7 @@ declare const ParameterNumberSlider: React$1.ForwardRefExoticComponent<CommonPar
     captionTestId?: string;
     title?: string;
 } & Omit<SliderProps, "id" | "aria-label" | "options"> & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterNumberSliderInner: React$1.ForwardRefExoticComponent<Omit<SliderProps, "id" | "aria-label" | "options"> & React$1.RefAttributes<HTMLInputElement>>;
 
 type LinkNodeProps = NonNullable<LinkParamValue>;
@@ -3783,7 +3799,10 @@ declare const ParameterSelect: React$1.ForwardRefExoticComponent<CommonParameter
     captionTestId?: string;
     title?: string;
 } & CommonParameterSelectProps & React$1.InputHTMLAttributes<HTMLSelectElement> & React$1.RefAttributes<HTMLSelectElement>>;
-/** @example  <ParameterSelectInner options={[{ label: 'option label', value: 0}]} />*/
+/**
+ * @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component.
+ * @example <ParameterSelectInner options={[{ label: 'option label', value: 0}]} />
+ */
 declare const ParameterSelectInner: React$1.ForwardRefExoticComponent<Omit<ParameterSelectProps, "label" | "id"> & React$1.RefAttributes<HTMLSelectElement>>;
 
 type ParameterSelectSliderProps = CommonParameterInputProps & Omit<SliderProps, 'id' | 'aria-label' | 'value' | 'onChange' | 'min' | 'max' | 'step' | 'showNumberInput'> & {
@@ -3825,6 +3844,7 @@ declare const ParameterSelectSlider: React$1.ForwardRefExoticComponent<CommonPar
      */
     onChange: (value: string | undefined) => void;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterSelectSliderInner: React$1.ForwardRefExoticComponent<Omit<ParameterSelectSliderProps, "caption" | "title" | "errorTestId" | "captionTestId" | "menuItems" | "actionItems" | keyof CommonParameterProps> & React$1.RefAttributes<HTMLInputElement>>;
 
 /** A function that extracts all common props and element props
@@ -3892,7 +3912,10 @@ declare const ParameterTextarea: React$1.ForwardRefExoticComponent<CommonParamet
     captionTestId?: string;
     title?: string;
 } & React$1.TextareaHTMLAttributes<HTMLTextAreaElement> & React$1.RefAttributes<HTMLTextAreaElement>>;
-/** @example <ParameterTextareaInner /> */
+/**
+ * @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component.
+ * @example <ParameterTextareaInner />
+ */
 declare const ParameterTextareaInner: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLTextAreaElement> & React$1.RefAttributes<HTMLTextAreaElement>>;
 
 type ParameterToggleInnerProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> & {
@@ -3912,6 +3935,7 @@ declare const ParameterToggle: React$1.ForwardRefExoticComponent<CommonParameter
     type: "checkbox" | "radio";
     withoutIndeterminateState?: boolean;
 } & React$1.RefAttributes<HTMLInputElement>>;
+/** @requires ParameterShell - Must be rendered inside a `<ParameterShell>` component. */
 declare const ParameterToggleInner: React$1.ForwardRefExoticComponent<Omit<React$1.InputHTMLAttributes<HTMLInputElement>, "type"> & {
     type: "checkbox" | "radio";
     withoutIndeterminateState?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/design-system",
-  "version": "20.50.1-alpha.1+b0bc8e0346",
+  "version": "20.50.1-alpha.16+940a311ed2",
   "description": "Uniform design system components",
   "license": "SEE LICENSE IN LICENSE.txt",
   "exports": {
@@ -35,8 +35,8 @@
     "@storybook/react-vite": "10.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
-    "@uniformdev/canvas": "^20.50.1-alpha.1+b0bc8e0346",
-    "@uniformdev/richtext": "^20.50.1-alpha.1+b0bc8e0346",
+    "@uniformdev/canvas": "^20.50.1-alpha.16+940a311ed2",
+    "@uniformdev/richtext": "^20.50.1-alpha.16+940a311ed2",
     "autoprefixer": "10.4.21",
     "hygen": "6.2.11",
     "jsdom": "20.0.3",
@@ -88,5 +88,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b0bc8e034642a423b0309bfed8be51f7966aa5d6"
+  "gitHead": "940a311ed2ab119a1d58fc652a91e1818fe746e8"
 }