@graphty/compact-mantine 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -436,9 +436,11 @@ export declare const COMPACT_SIZING: {
  * @param props.defaultOpacity - The opacity shown while the reader has set none of their own
  * @param props.onColorChange - Called with the new colour, or with `undefined` when the control is reset
  * @param props.onOpacityChange - Called with the new opacity, or with `undefined` when the control is reset
+ * @param props.onChange - Called once per gesture with both halves of the colour, whichever of them moved
  * @param props.label - The field's name, drawn above the control and used to name the group
  * @param props.showOpacity - Whether to offer an opacity box beside the colour
  * @param props.disabled - Whether the control cannot be used at all
+ * @param props.disabledReason - One sentence saying why the control is off, drawn only while it is off
  * @param props.onFocus - Called when the hex box or the opacity box takes focus
  * @param props.onBlur - Called when the hex box or the opacity box loses focus
  * @returns The joined colour control, and its reset button when something has been set
@@ -456,7 +458,7 @@ export declare const COMPACT_SIZING: {
  * </PopoutManager>
  * ```
  */
-export declare function CompactColorInput({ color, defaultColor, opacity, defaultOpacity, onColorChange, onOpacityChange, label, showOpacity, disabled, onFocus, onBlur, }: CompactColorInputProps): default_2.JSX.Element;
+export declare function CompactColorInput({ color, defaultColor, opacity, defaultOpacity, onColorChange, onOpacityChange, onChange, label, showOpacity, disabled, disabledReason, onFocus, onBlur, }: CompactColorInputProps): default_2.JSX.Element;
 
 /**
  * Props for the CompactColorInput component.
@@ -499,6 +501,46 @@ export declare interface CompactColorInputProps {
      * The percentage comes first; the event that caused the change is second.
      */
     onOpacityChange?: ChangeHandler<number | undefined>;
+    /**
+     * Called once per gesture with BOTH halves of the colour, whichever of them
+     * moved.
+     *
+     * Reach for this one, alone, whenever you drive the control from your own
+     * state. `onColorChange` and `onOpacityChange` are kept for call sites that
+     * already use them, but they cannot carry a gesture that moves both halves
+     * at once.
+     *
+     * THE DEFECT THIS REPAIRS, reproduced at runtime rather than reasoned
+     * about: dragging in the picker used to call `onColorChange` and then
+     * `onOpacityChange` back to back inside one React batch. A controlled
+     * consumer builds its next state out of the props it is holding -- the only
+     * snapshot it has -- and both callbacks run against the SAME pre-gesture
+     * snapshot, so the second one writes a state rebuilt from a colour the
+     * first one had already replaced. A test in this package
+     * (tests/components/CompactColorInput.test.tsx, "the two separate callbacks
+     * cannot carry one gesture") drives a picker swatch and watches the second
+     * write arrive as `{opacity: 50}` with the new colour gone. The application
+     * had already forked this whole component to escape it.
+     *
+     * Both halves are always passed, so a consumer never has to remember which
+     * one moved -- the same shape `GradientEditor` already uses for its stops
+     * and its direction. `undefined` keeps its meaning from the props: the
+     * reader has chosen nothing for that half and the default is showing.
+     *
+     * Supplying this ALONGSIDE `onColorChange` or `onOpacityChange` makes every
+     * gesture write twice. Pick one route.
+     * @example
+     * ```tsx
+     * <CompactColorInput
+     *     label="Fill"
+     *     color={style.color}
+     *     opacity={style.opacity}
+     *     defaultColor="#5B8FF9"
+     *     onChange={(color, opacity) => { setStyle({...style, color, opacity}); }}
+     * />
+     * ```
+     */
+    onChange?: (color: string | undefined, opacity: number | undefined, event?: default_2.SyntheticEvent) => void;
     /**
      * The field's name, drawn above the control and used to name the group the
      * three controls sit in.
@@ -522,6 +564,22 @@ export declare interface CompactColorInputProps {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * One sentence saying why the control is off, shown only while `disabled`
+     * is true.
+     *
+     * It is appended to the control's own name after a full stop and drawn as
+     * the tooltip -- "Glow colour. Glow is not drawn yet" -- and it also joins
+     * the accessible description of the swatch, the hex box and the opacity
+     * box, so the reason reaches a pointer user and a screen reader user alike.
+     * With no `label` to append to, the sentence stands on its own.
+     *
+     * THE DEFECT THIS REPAIRS: a disabled colour control used to be dimmed and
+     * silent, so a reader who could not open the picker had no route at all to
+     * learning why -- spec:6641 asks for the one reason to travel with the
+     * disabled ink, and until now this component had nowhere to put it.
+     */
+    disabledReason?: string;
     /** Called when the hex box or the opacity box takes focus. Forwarded unchanged. */
     onFocus?: default_2.FocusEventHandler<HTMLInputElement>;
     /**
@@ -902,8 +960,8 @@ export declare const compactThemeOverride: {
     } | undefined;
     radius?: {
         [x: string & {}]: string | undefined;
-        xs?: string | undefined;
         sm?: string | undefined;
+        xs?: string | undefined;
         md?: string | undefined;
         lg?: string | undefined;
         xl?: string | undefined;
@@ -912,40 +970,40 @@ export declare const compactThemeOverride: {
     spacing?: {
         [x: number]: string | undefined;
         [x: string & {}]: string | undefined;
-        xs?: string | undefined;
         sm?: string | undefined;
+        xs?: string | undefined;
         md?: string | undefined;
         lg?: string | undefined;
         xl?: string | undefined;
     } | undefined;
     fontSizes?: {
         [x: string & {}]: string | undefined;
-        xs?: string | undefined;
         sm?: string | undefined;
+        xs?: string | undefined;
         md?: string | undefined;
         lg?: string | undefined;
         xl?: string | undefined;
     } | undefined;
     lineHeights?: {
         [x: string & {}]: string | undefined;
-        xs?: string | undefined;
         sm?: string | undefined;
+        xs?: string | undefined;
         md?: string | undefined;
         lg?: string | undefined;
         xl?: string | undefined;
     } | undefined;
     breakpoints?: {
         [x: string & {}]: string | undefined;
-        xs?: string | undefined;
         sm?: string | undefined;
+        xs?: string | undefined;
         md?: string | undefined;
         lg?: string | undefined;
         xl?: string | undefined;
     } | undefined;
     shadows?: {
         [x: string & {}]: string | undefined;
-        xs?: string | undefined;
         sm?: string | undefined;
+        xs?: string | undefined;
         md?: string | undefined;
         lg?: string | undefined;
         xl?: string | undefined;
@@ -2704,6 +2762,7 @@ export declare interface IconGroupOption {
  * @param props.labelledBy - The `id` of the element that already names the group
  * @param props.name - The name shared by the group's radio inputs
  * @param props.disabled - Whether the whole group cannot be used
+ * @param props.disabledReason - One sentence saying why the group is off, drawn only while it is off
  * @param props.hybrid - Draw the word beside the drawing on the selected option only
  * @param props.width - How wide the track is drawn, or `"fill"` to take the rest of the row
  * @param props.trailing - The row's 24px trailing slot
@@ -2781,6 +2840,23 @@ export declare interface IconGroupRowProps {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * One sentence saying why the whole group is off, shown only while
+     * `disabled` is true.
+     *
+     * It is appended to the group's own name after a full stop and drawn as the
+     * row's tooltip -- "Node shape. Load data first" -- and it joins the
+     * group's accessible description, so the reason reaches a pointer user and
+     * a screen reader user alike. With no `label` to append to, the sentence
+     * stands on its own.
+     *
+     * It says nothing about one option: a single unavailable choice is
+     * `disabled` on that option, and its own word still names it. THE DEFECT
+     * THIS REPAIRS: a whole group drawn dimmed with no explanation reads as a
+     * broken control, which is what spec:6641 forbids -- and until now this row
+     * had nowhere to put the one reason.
+     */
+    disabledReason?: string;
     /**
      * Draw the word beside the drawing on the selected option only.
      *
@@ -4774,6 +4850,7 @@ export declare interface SparklineRowProps {
  * @param props.suffix - A unit written after the number
  * @param props.hideControls - Whether to leave out the up and down steppers, which are left out by default
  * @param props.disabled - Whether the control cannot be used at all
+ * @param props.disabledReason - One sentence saying why the control is off, drawn only while it is off
  * @param props.onFocus - Called when the control takes focus
  * @param props.onBlur - Called when the control loses focus, after the number has been committed
  * @returns The number box, and its reset button when a number has been entered
@@ -4792,7 +4869,7 @@ export declare interface SparklineRowProps {
  * />
  * ```
  */
-export declare function StyleNumberInput({ label, value, defaultValue, onChange, min, max, step, decimalScale, suffix, hideControls, disabled, onFocus, onBlur, }: StyleNumberInputProps): default_2.JSX.Element;
+export declare function StyleNumberInput({ label, value, defaultValue, onChange, min, max, step, decimalScale, suffix, hideControls, disabled, disabledReason, onFocus, onBlur, }: StyleNumberInputProps): default_2.JSX.Element;
 
 /**
  * Props for the StyleNumberInput component.
@@ -4846,6 +4923,22 @@ export declare interface StyleNumberInputProps {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * One sentence saying why the control is off, shown only while `disabled`
+     * is true.
+     *
+     * It is appended to the control's own name after a full stop and drawn as
+     * the tooltip -- "Width. Load data first" -- and it also joins the
+     * control's accessible description, so a screen reader reads the reason out
+     * instead of announcing an unexplained unavailable control.
+     *
+     * Write it as a whole sentence naming what would make the control usable
+     * again. THE DEFECT THIS REPAIRS: a disabled control here used to be dimmed
+     * and silent, so a reader who could not type into it had no route at all to
+     * learning why -- spec:6641 asks for the reason to travel with the ink, and
+     * until now this component had nowhere to put it.
+     */
+    disabledReason?: string;
     /** Called when the control takes focus. Forwarded unchanged. */
     onFocus?: default_2.FocusEventHandler<HTMLInputElement>;
     /**
@@ -4877,6 +4970,7 @@ export declare interface StyleNumberInputProps {
  * @param props.options - The choices offered
  * @param props.onChange - Called with the new choice, or with `undefined` when the control is reset
  * @param props.disabled - Whether the control cannot be used at all
+ * @param props.disabledReason - One sentence saying why the control is off, drawn only while it is off
  * @param props.onFocus - Called when the control takes focus
  * @param props.onBlur - Called when the control loses focus
  * @returns The dropdown, and its reset button when a choice has been made
@@ -4896,7 +4990,7 @@ export declare interface StyleNumberInputProps {
  * />
  * ```
  */
-export declare function StyleSelect({ label, value, defaultValue, options, onChange, disabled, onFocus, onBlur, }: StyleSelectProps): default_2.JSX.Element;
+export declare function StyleSelect({ label, value, defaultValue, options, onChange, disabled, disabledReason, onFocus, onBlur, }: StyleSelectProps): default_2.JSX.Element;
 
 /**
  * One choice in a {@link StyleSelect}.
@@ -4943,6 +5037,23 @@ export declare interface StyleSelectProps {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * One sentence saying why the control is off, shown only while `disabled`
+     * is true.
+     *
+     * It is appended to the control's own name after a full stop and drawn as
+     * the tooltip -- "Fill. Load data first" -- and it also joins the control's
+     * accessible description, so a screen reader reads the reason out instead
+     * of announcing an unexplained unavailable control.
+     *
+     * Write it as a whole sentence naming what would make the control usable
+     * again, not as a restatement that it is off. THE DEFECT THIS REPAIRS: a
+     * disabled control here used to be dimmed and silent, so a reader who could
+     * not press it had no route at all to learning why -- spec:6641 asks for
+     * the reason to travel with the ink, and until now this component had
+     * nowhere to put it.
+     */
+    disabledReason?: string;
     /** Called when the control takes focus. Forwarded unchanged. */
     onFocus?: default_2.FocusEventHandler<HTMLInputElement>;
     /** Called when the control loses focus. Forwarded unchanged. */
@@ -4986,6 +5097,9 @@ export declare const SWATCH_COLORS_HEXA: readonly ["#5B8FF9FF", "#FF6B6BFF", "#6
  * @param props.control - Which control to draw: a 16px checkbox, or a 28x16 switch for a live mode
  * @param props.trailing - What to put in the fixed 24px slot at the end of the row
  * @param props.disabled - Whether the toggle can be changed
+ * @param props.disabledReason - One sentence saying why the toggle is off, drawn only while it is off
+ * @param props.bound - Whether the boolean comes from a data attribute rather than being set by hand
+ * @param props.boundDescription - What a screen reader says about a bound row, defaulting to `fieldBound`
  * @param props.onFocus - Called when the control takes focus
  * @param props.onBlur - Called when the control loses focus
  * @returns The toggle row
@@ -4997,7 +5111,7 @@ export declare const SWATCH_COLORS_HEXA: readonly ["#5B8FF9FF", "#FF6B6BFF", "#6
  * </ToggleRowGroup>
  * ```
  */
-export declare function ToggleRow({ label, checked, defaultChecked, onChange, control, trailing, disabled, onFocus, onBlur, }: ToggleRowProps): default_2.JSX.Element;
+export declare function ToggleRow({ label, checked, defaultChecked, onChange, control, trailing, disabled, disabledReason, bound, boundDescription, onFocus, onBlur, }: ToggleRowProps): default_2.JSX.Element;
 
 /**
  * The column two or more toggle rows are packed into.
@@ -5126,6 +5240,48 @@ export declare interface ToggleRowProps {
      * unavailable rather than merely looking it.
      */
     disabled?: boolean;
+    /**
+     * One sentence saying why the toggle is off, shown only while `disabled` is
+     * true.
+     *
+     * It is appended to the row's own word after a full stop and becomes the
+     * row's tooltip -- "Legend. Nothing is encoded yet" -- and it joins the
+     * control's accessible description, so the reason reaches a pointer user
+     * and a screen reader user alike.
+     *
+     * THE DEFECT THIS REPAIRS, and it was the sharper half of the two: this row
+     * used to hardcode its tooltip as `wrapperProps = {title: label}`, so a
+     * call site could not append a reason even by hand. A disabled toggle was
+     * therefore dimmed and permanently unexplained, which is what spec:6641
+     * forbids. The caller supplies the sentence; the library never invents one,
+     * because only the call site knows what would turn the control back on.
+     */
+    disabledReason?: string;
+    /**
+     * Whether the boolean comes from a data attribute rather than being set by
+     * hand.
+     *
+     * The row draws a filled attribute glyph beside its word -- the same filled
+     * glyph `PanelField` uses to say the same thing -- so a panel can say "this
+     * follows the data" without spending a row on a fixed-or-by-attribute
+     * switch. A boolean channel can be bound just as a numeric one can, and
+     * until now `PanelField` was the only control in the library able to say
+     * so, which is why a bound boolean had to be drawn as a number field or not
+     * drawn at all.
+     * @default false
+     */
+    bound?: boolean;
+    /**
+     * What a screen reader says about a row whose value comes from a data
+     * attribute. Only used when `bound` is set.
+     *
+     * Defaults to the `fieldBound` string, so translating it once through
+     * `LabelsProvider` covers every bound control in the panel. Pass it here
+     * only to say something more specific about one row, and pass an empty
+     * string to say nothing -- byte for byte the contract `PanelField` already
+     * documents.
+     */
+    boundDescription?: string;
     /** Called when the control takes focus. */
     onFocus?: default_2.FocusEventHandler<HTMLInputElement>;
     /** Called when the control loses focus. */
@@ -5160,6 +5316,9 @@ export declare interface ToggleRowProps {
  * @param props.defaultChecked - Whether the toggle starts on, when the component keeps its own state
  * @param props.onChange - Called with the new state first and the event that caused it second
  * @param props.disabled - Whether the toggle can be changed
+ * @param props.disabledReason - One sentence saying why the toggle is off, drawn only while it is off
+ * @param props.bound - Whether the boolean comes from a data attribute rather than being set by hand
+ * @param props.boundDescription - What a screen reader says about a bound toggle, defaulting to `fieldBound`
  * @param props.onFocus - Called when the checkbox takes focus
  * @param props.onBlur - Called when the checkbox loses focus
  * @param props.children - The controls shown only while the feature is on
@@ -5172,7 +5331,7 @@ export declare interface ToggleRowProps {
  * </ToggleWithContent>
  * ```
  */
-export declare function ToggleWithContent({ label, checked, defaultChecked, onChange, disabled, onFocus, onBlur, children, }: ToggleWithContentProps): default_2.JSX.Element;
+export declare function ToggleWithContent({ label, checked, defaultChecked, onChange, disabled, disabledReason, bound, boundDescription, onFocus, onBlur, children, }: ToggleWithContentProps): default_2.JSX.Element;
 
 /**
  * Props for the ToggleWithContent component.
@@ -5215,6 +5374,47 @@ export declare interface ToggleWithContentProps {
      * revealed; disable them yourself if they should not be touched either.
      */
     disabled?: boolean;
+    /**
+     * One sentence saying why the toggle is off, shown only while `disabled` is
+     * true.
+     *
+     * It is appended to the toggle's own word after a full stop and becomes its
+     * tooltip -- "Glow. Glow is not drawn yet" -- and it joins the control's
+     * accessible description, so the reason reaches a pointer user and a screen
+     * reader user alike.
+     *
+     * THE DEFECT THIS REPAIRS: a feature that cannot be turned on yet used to
+     * be drawn as a dimmed checkbox with nothing to say for itself, which reads
+     * as a broken control rather than as an unfinished feature. spec:6641 asks
+     * for the one reason to travel with the disabled ink; until now this
+     * component had nowhere to put it. The caller supplies the sentence -- only
+     * the call site knows what would turn the feature back on.
+     */
+    disabledReason?: string;
+    /**
+     * Whether the boolean comes from a data attribute rather than being set by
+     * hand.
+     *
+     * The toggle draws a filled attribute glyph beside its word -- the same
+     * filled glyph `PanelField` uses to say the same thing -- so a panel can
+     * say "this follows the data" without spending a row on a
+     * fixed-or-by-attribute switch. A boolean channel can be bound just as a
+     * numeric one can, and until now `PanelField` was the only control in the
+     * library able to say so.
+     * @default false
+     */
+    bound?: boolean;
+    /**
+     * What a screen reader says about a toggle whose value comes from a data
+     * attribute. Only used when `bound` is set.
+     *
+     * Defaults to the `fieldBound` string, so translating it once through
+     * `LabelsProvider` covers every bound control in the panel. Pass it here
+     * only to say something more specific about one toggle, and pass an empty
+     * string to say nothing -- byte for byte the contract `PanelField` already
+     * documents.
+     */
+    boundDescription?: string;
     /** Called when the checkbox takes focus. */
     onFocus?: default_2.FocusEventHandler<HTMLInputElement>;
     /** Called when the checkbox loses focus. */
@@ -5434,9 +5634,6 @@ export declare function usePanelLabels(): boolean;
  */
 export declare function usePopoutRegion(): string | null;
 
-/** The released version of this package. */
-export declare const VERSION = "0.6.0";
-
 export { }