sheerly 0.0.1 → 0.0.2

package/src/sheet.tsx

@@ -1,5 +1,6 @@
-import type { ButtonHTMLAttributes, DialogHTMLAttributes, HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ButtonHTMLAttributes, DialogHTMLAttributes, ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
 export interface SheetProps extends DialogHTMLAttributes<HTMLDialogElement> {
   'data-side'?: 'right' | 'left' | 'top' | 'bottom'
@@ -9,32 +10,71 @@ export interface SheetProps extends DialogHTMLAttributes<HTMLDialogElement> {
  * Native <dialog> that slides in from an edge. Open via invoker command
  * (`command="show-modal"`) or `.showModal()`. Add `closedby="any"` for
  * light-dismiss.
+ *
+ * @example
+ * <button commandfor="s" command="show-modal">Open</button>
+ * <Sheet id="s" data-side="right" closedby="any">
+ *   <SheetHeader><SheetTitle>Filters</SheetTitle></SheetHeader>
+ *   <SheetBody>…</SheetBody>
+ * </Sheet>
  */
 export function Sheet({ className, ...props }: SheetProps) {
   return <dialog className={cn('sheerly-sheet', className)} {...props} />
 }
 
-export function SheetHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-sheet-header', className)} {...props} />
+export type SheetHeaderProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function SheetHeader<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SheetHeaderProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-sheet-header', className)} {...props} />
 }
 
-export function SheetTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
-  return <h3 className={cn('sheerly-sheet-title', className)} {...props} />
+export type SheetTitleProps<T extends ElementType = 'h3'> = PolymorphicProps<T>
+
+export function SheetTitle<T extends ElementType = 'h3'>({
+  as,
+  className,
+  ...props
+}: SheetTitleProps<T>) {
+  const Tag = as ?? 'h3'
+  return <Tag className={cn('sheerly-sheet-title', className)} {...props} />
 }
 
-export function SheetDescription({
+export type SheetDescriptionProps<T extends ElementType = 'p'> = PolymorphicProps<T>
+
+export function SheetDescription<T extends ElementType = 'p'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLParagraphElement>) {
-  return <p className={cn('sheerly-sheet-description', className)} {...props} />
+}: SheetDescriptionProps<T>) {
+  const Tag = as ?? 'p'
+  return <Tag className={cn('sheerly-sheet-description', className)} {...props} />
 }
 
-export function SheetBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-sheet-body', className)} {...props} />
+export type SheetBodyProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function SheetBody<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SheetBodyProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-sheet-body', className)} {...props} />
 }
 
-export function SheetFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-sheet-footer', className)} {...props} />
+export type SheetFooterProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function SheetFooter<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SheetFooterProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-sheet-footer', className)} {...props} />
 }
 
 export function SheetClose({

package/src/skeleton.tsx

@@ -1,8 +1,22 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export type SkeletonProps = HTMLAttributes<HTMLDivElement>
+export type SkeletonProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function Skeleton({ className, ...props }: SkeletonProps) {
-  return <div className={cn('sheerly-skeleton', className)} {...props} />
+/**
+ * A pulsing placeholder. Set width/height/border-radius inline.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Skeleton style={{ width: 200, height: 20, borderRadius: 6 }} />
+ */
+export function Skeleton<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SkeletonProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-skeleton', className)} {...props} />
 }

package/src/slider.tsx

@@ -1,8 +1,14 @@
 import type { InputHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
 
+/**
+ * A range `<input>`. Set `min` / `max` / `step` / `value`.
+ *
+ * @example
+ * <Slider min={0} max={100} defaultValue={50} />
+ */
 export function Slider({ className, ...props }: SliderProps) {
   return <input type="range" className={cn('sheerly-slider', className)} {...props} />
 }

package/src/spinner.tsx

@@ -1,24 +1,37 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
-  'data-size'?: 'sm' | 'default' | 'md' | 'lg'
-}
+export type SpinnerProps<T extends ElementType = 'span'> = PolymorphicProps<
+  T,
+  { 'data-size'?: 'sm' | 'default' | 'md' | 'lg' }
+>
 
 /**
  * Loading spinner. The glyph is embedded in CSS (masked ::before), so no SVG
  * child is needed — this renders a bare <span>. It inherits the current text
  * color. Pass an <svg> child if you prefer to ship your own icon.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `span`).
+ *
+ * @example
+ * <Spinner data-size="lg" />
  */
-export function Spinner({ className, children, ...props }: SpinnerProps) {
+export function Spinner<T extends ElementType = 'span'>({
+  as,
+  className,
+  children,
+  ...props
+}: SpinnerProps<T>) {
+  const Tag = as ?? 'span'
   return (
-    <span
+    <Tag
       className={cn('sheerly-spinner', className)}
       role="status"
       aria-label="Loading"
       {...props}
     >
       {children}
-    </span>
+    </Tag>
   )
 }

package/src/switch.tsx

@@ -1,11 +1,17 @@
 import type { InputHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export interface SwitchProps
   extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'role'> {
   'data-size'?: 'default' | 'sm'
 }
 
+/**
+ * A toggle switch (checkbox with `role="switch"`).
+ *
+ * @example
+ * <Switch defaultChecked />
+ */
 export function Switch({ className, ...props }: SwitchProps) {
   return (
     <input

package/src/table.css

@@ -1,6 +1,5 @@
 /* Wrapper enabling horizontal scroll on overflow */
 .sheerly-table-container {
-  position: relative;
   width: 100%;
   overflow-x: auto;
 }

package/src/table.tsx

@@ -1,14 +1,30 @@
-import type { HTMLAttributes, TableHTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType, TableHTMLAttributes } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export type TableContainerProps = HTMLAttributes<HTMLDivElement>
+export type TableContainerProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function TableContainer({ className, ...props }: TableContainerProps) {
-  return <div className={cn('sheerly-table-container', className)} {...props} />
+export function TableContainer<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: TableContainerProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-table-container', className)} {...props} />
 }
 
 export type TableProps = TableHTMLAttributes<HTMLTableElement>
 
+/**
+ * A data table. Use semantic HTML inside (no classes on inner elements); wrap
+ * in a <TableContainer> for horizontal overflow scroll.
+ *
+ * @example
+ * <Table>
+ *   <thead><tr><th>Name</th></tr></thead>
+ *   <tbody><tr><td>Ada</td></tr></tbody>
+ * </Table>
+ */
 export function Table({ className, ...props }: TableProps) {
   return <table className={cn('sheerly-table', className)} {...props} />
 }

package/src/tabs.tsx

@@ -1,18 +1,49 @@
-import type { ButtonHTMLAttributes, HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ButtonHTMLAttributes, ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export type TabsProps = HTMLAttributes<HTMLDivElement>
+export type TabsProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function Tabs({ className, ...props }: TabsProps) {
-  return <div className={cn('sheerly-tabs', className)} {...props} />
+/**
+ * A tabbed interface. Compose a <TabsList> of <TabsTrigger>s with matching
+ * <TabsContent> panels (hide inactive panels with `hidden`).
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Tabs>
+ *   <TabsList>
+ *     <TabsTrigger aria-selected>Account</TabsTrigger>
+ *     <TabsTrigger>Password</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent>…</TabsContent>
+ *   <TabsContent hidden>…</TabsContent>
+ * </Tabs>
+ */
+export function Tabs<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: TabsProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-tabs', className)} {...props} />
 }
 
-export interface TabsListProps extends HTMLAttributes<HTMLDivElement> {
-  'data-variant'?: 'line'
-}
+export type TabsListProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-variant'?: 'line' }
+>
 
-export function TabsList({ className, role = 'tablist', ...props }: TabsListProps) {
-  return <div role={role} className={cn('sheerly-tabs-list', className)} {...props} />
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ */
+export function TabsList<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: TabsListProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag role="tablist" className={cn('sheerly-tabs-list', className)} {...props} />
 }
 
 export interface TabsTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -25,14 +56,16 @@ export function TabsTrigger({ className, role = 'tab', ...props }: TabsTriggerPr
   )
 }
 
-export type TabsContentProps = HTMLAttributes<HTMLDivElement>
+export type TabsContentProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function TabsContent({
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ */
+export function TabsContent<T extends ElementType = 'div'>({
+  as,
   className,
-  role = 'tabpanel',
   ...props
-}: TabsContentProps) {
-  return (
-    <div role={role} className={cn('sheerly-tabs-content', className)} {...props} />
-  )
+}: TabsContentProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag role="tabpanel" className={cn('sheerly-tabs-content', className)} {...props} />
 }

package/src/textarea.tsx

@@ -1,8 +1,14 @@
 import type { TextareaHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>
 
+/**
+ * A multiline text field. Auto-grows with content (`field-sizing: content`).
+ *
+ * @example
+ * <Textarea placeholder="Type your message…" />
+ */
 export function Textarea({ className, ...props }: TextareaProps) {
   return <textarea className={cn('sheerly-textarea', className)} {...props} />
 }

package/src/toggle.tsx

@@ -1,5 +1,5 @@
 import type { ChangeEventHandler, LabelHTMLAttributes, ReactNode } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export interface ToggleProps
   extends Omit<LabelHTMLAttributes<HTMLLabelElement>, 'onChange'> {
@@ -17,6 +17,13 @@ export interface ToggleProps
   children?: ReactNode
 }
 
+/**
+ * A two-state toggle button. Works uncontrolled (no JS) or controlled via
+ * `pressed` / `onPressedChange`.
+ *
+ * @example
+ * <Toggle defaultPressed data-variant="outline">Bold</Toggle>
+ */
 export function Toggle({
   className,
   pressed,

package/src/tooltip.tsx

@@ -1,16 +1,35 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export type TooltipProps = HTMLAttributes<HTMLSpanElement>
+export type TooltipProps<T extends ElementType = 'span'> = PolymorphicProps<T>
 
-/** Wrapper carrying the anchor. Nest the trigger + content inside. */
-export function Tooltip({ className, ...props }: TooltipProps) {
-  return <span className={cn('sheerly-tooltip', className)} {...props} />
+/**
+ * Wrapper carrying the anchor. Nest the trigger + content inside.
+ *
+ * @example
+ * <Tooltip>
+ *   <Button interestfor="tt">Hover me</Button>
+ *   <TooltipContent id="tt" popover="hint">More info</TooltipContent>
+ * </Tooltip>
+ */
+export function Tooltip<T extends ElementType = 'span'>({
+  as,
+  className,
+  ...props
+}: TooltipProps<T>) {
+  const Tag = as ?? 'span'
+  return <Tag className={cn('sheerly-tooltip', className)} {...props} />
 }
 
-export type TooltipContentProps = HTMLAttributes<HTMLSpanElement>
+export type TooltipContentProps<T extends ElementType = 'span'> = PolymorphicProps<T>
 
 /** The floating label. Give it `popover="hint"` and an `id` matched by the trigger's `interestfor`. */
-export function TooltipContent({ className, ...props }: TooltipContentProps) {
-  return <span className={cn('sheerly-tooltip-content', className)} {...props} />
+export function TooltipContent<T extends ElementType = 'span'>({
+  as,
+  className,
+  ...props
+}: TooltipContentProps<T>) {
+  const Tag = as ?? 'span'
+  return <Tag className={cn('sheerly-tooltip-content', className)} {...props} />
 }

package/src/typography.tsx

@@ -1,13 +1,27 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export interface TypographyProps extends HTMLAttributes<HTMLDivElement> {}
+export type TypographyProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
 /**
  * A prose wrapper. Unlike shadcn (per-element utility classes), Sheerly styles
  * every child element (h1–h4, p, a, blockquote, ul/ol, li, code, table, …) via
  * one `.sheerly-typography` class — just render semantic HTML inside it.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Typography as="article">
+ *   <h1>Title</h1>
+ *   <p>Some <a href="#">prose</a> with a <code>token</code>.</p>
+ * </Typography>
  */
-export function Typography({ className, ...props }: TypographyProps) {
-  return <div className={cn('sheerly-typography', className)} {...props} />
+export function Typography<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: TypographyProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-typography', className)} {...props} />
 }

package/src/utils/polymorphic.ts

@@ -0,0 +1,19 @@
+import type { ComponentPropsWithoutRef, ElementType } from 'react'
+
+/**
+ * Props for a polymorphic component: an optional `as` that swaps the rendered
+ * element, with the remaining props inferred from that element (so `href` is
+ * valid & checked when `as="a"`, etc.).
+ *
+ * `Extra` merges component-specific props (e.g. typed `data-*` unions) on top.
+ *
+ * No hooks, no `forwardRef` — matches Sheerly's thin, hookless wrapper style.
+ */
+export type PolymorphicProps<
+  T extends ElementType,
+  Extra = object,
+> = {
+  /** The element or component to render. */
+  as?: T
+} & Extra &
+  Omit<ComponentPropsWithoutRef<T>, 'as' | keyof Extra>