@recursica/mui-adapter 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @recursica/mui-adapter
 
+## 0.28.0
+
+### Minor Changes
+
+- adab23c: Revised Dropwdown, Menu, Breadcrumb
+
+## 0.27.0
+
+### Minor Changes
+
+- d171a96: Update revision to latest
+
+### Patch Changes
+
+- Updated dependencies [d171a96]
+  - @recursica/adapter-common@0.19.0
+
 ## 0.26.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -767,6 +767,45 @@ declare type MenuItemProps = RecursicaOverStyled<MenuItemProps_2>;
 
 declare type MenuProps = RecursicaOverStyled<MenuProps_2 & RecursicaMenuProps>;
 
+/**
+ * mergeClassNames
+ *
+ * Per-slot merge for a `classNames` prop against Recursica's own CSS-module classes. This is
+ * NOT the same shape as `withCallerOverride`: the caller's value must never fully replace ours,
+ * because the underlying library's `classNames` slots are singular strings — replacing one
+ * outright would drop the component's own module styles, not just extend them. Each slot keeps
+ * Recursica's class and appends the caller's class for that slot if they supplied one.
+ *
+ * Merges over the UNION of slots in `ours` and `callerValue`, not just `ours`'s keys — a caller
+ * may target a slot Recursica doesn't set a default class for (e.g. a library slot we never
+ * needed to style ourselves). Restricting the loop to `ours`'s keys would silently drop that
+ * slot instead of passing it through, the same class of prop-leakage bug this whole pattern
+ * exists to prevent.
+ *
+ * @param ours - Recursica's own per-slot classNames (CSS module classes)
+ * @param callerValue - The caller's `classNames` prop, if any
+ * @returns a new classNames object covering every slot named by either side
+ */
+export declare function mergeClassNames<T extends Record<string, string | undefined>>(ours: T, callerValue: Partial<Record<keyof T, string>> | undefined): T;
+
+/**
+ * mergeStyles
+ *
+ * Per-slot merge for a `styles` prop (e.g. Mantine's StylesApi) against Recursica's own default
+ * inline styles for that slot. Mirrors `mergeClassNames`'s shape but the merge is a plain object
+ * merge instead of a string concat, since each slot's value is a `CSSProperties` object, not a
+ * class list: the caller's individual style properties override ours property-by-property
+ * without dropping properties they didn't touch.
+ *
+ * Merges over the UNION of slots in `ours` and `callerValue`, not just `ours`'s keys — same
+ * reasoning as `mergeClassNames`: a caller may target a slot Recursica has no default for.
+ *
+ * @param ours - Recursica's own per-slot default styles, if any
+ * @param callerValue - The caller's `styles` prop, if any
+ * @returns a new styles object covering every slot named by either side
+ */
+export declare function mergeStyles<T extends Record<string, default_2.CSSProperties | undefined>>(ours: T, callerValue: Partial<Record<keyof T, default_2.CSSProperties>> | undefined): T;
+
 export declare const Modal: typeof rawComponents.Modal;
 
 declare const Modal_2: typeof ModalRoot & {
@@ -874,6 +913,32 @@ declare type NumberInputProps = RecursicaOverStyled<RecursicaNumberInputProps>;
 
 declare type OmitSx<T> = Omit<T, "sx">;
 
+/**
+ * omitUnsupportedProps
+ *
+ * Shared across every adapter. Where `filterStylingProps` blocks the fixed set of styling
+ * escape hatches (className, style, sx, etc.), this utility deletes a component-declared list
+ * of named props that component doesn't support at all — e.g. a native prop the underlying
+ * library exposes but Recursica intentionally doesn't map (`size`, `color`, `radius`, ...).
+ *
+ * `Omit<LibraryProps, "size">` on the public type already stops well-typed callers. This is the
+ * runtime backstop: a plain-JavaScript caller (or anyone forcing the type) can still put `size`
+ * on the props object, and without this it would leak straight through `...rest` into the
+ * wrapped component. Call this immediately after `filterStylingProps`, on every component
+ * (including sub-components merged onto a parent, e.g. `Table.Th`), declaring the omitted keys
+ * as a local `UNSUPPORTED_PROPS` const with a comment per prop explaining why it's unsupported.
+ *
+ * @param props - Props already run through `filterStylingProps`
+ * @param unsupportedProps - Component-declared list of prop names to delete. Typed as
+ *   `PropertyKey`, not `keyof T`, on purpose: `T` is the already-narrowed `rest`/`sanitizedProps`
+ *   type, which typically has these props `Omit<>`'d out of it already — the whole point of
+ *   `UNSUPPORTED_PROPS` is to still catch them at runtime. Type `UNSUPPORTED_PROPS` itself
+ *   against the underlying library's full props type instead, e.g.
+ *   `as const satisfies readonly (keyof MantineButtonProps)[]`.
+ * @returns `props` with every key in `unsupportedProps` removed
+ */
+export declare function omitUnsupportedProps<T extends Record<string, unknown>>(props: T, unsupportedProps: readonly PropertyKey[]): Partial<T>;
+
 export declare const Pagination: typeof rawComponents.Pagination;
 
 /**
@@ -1586,7 +1651,7 @@ declare interface RecursicaDatePickerProps_2 extends Omit<DatePickerProps, "valu
     style?: default_2.CSSProperties;
 }
 
-export declare interface RecursicaDropdownProps extends Omit<SelectProps, keyof default_2.HTMLAttributes<HTMLDivElement> | "size" | "variant" | "classes" | "inputProps" | "SelectDisplayProps" | "ref" | "error">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth">, ReadOnlyControlProps, RecursicaDropdownProps_2 {
+export declare interface RecursicaDropdownProps extends Omit<SelectProps, keyof default_2.HTMLAttributes<HTMLDivElement> | "size" | "variant" | "classes" | "inputProps" | "SelectDisplayProps" | "ref" | "error">, Pick<SelectProps, "onChange">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth" | "onChange">, ReadOnlyControlProps, RecursicaDropdownProps_2 {
 }
 
 /**
@@ -3308,6 +3373,23 @@ declare type TypographyProps_2 = RecursicaOverStyled<Omit<TypographyProps, "vari
  */
 export declare function useGlobalOverStyled(): boolean;
 
+/**
+ * withCallerOverride
+ *
+ * Resolves a single prop where Recursica supplies a default but the caller should be able to
+ * override it. Use this only when the default can't be expressed as a plain destructured default
+ * (`const { variant = "solid" } = props`) — e.g. the default is computed from other props/state
+ * inside the component body, so it isn't known until after `rest` has already been destructured.
+ *
+ * Do not rely on spread order for this (`{...sanitizedProps, ...overrides}` never carries this
+ * intent implicitly) — resolve the value explicitly and place the result in `overrides`.
+ *
+ * @param ourDefault - The value Recursica falls back to when the caller didn't supply one
+ * @param callerValue - The raw value from the caller's props, if any
+ * @returns `callerValue` if defined, else `ourDefault`
+ */
+export declare function withCallerOverride<T>(ourDefault: T, callerValue: T | undefined): T;
+
 /**
  * Universal execution barrier trapping readOnly states globally.
  * Natively delegates active logic down avoiding duplicative internal component bindings dynamically.