sheerly 0.0.1 → 0.0.3

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,38 +1,78 @@
-import type { ButtonHTMLAttributes, 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 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> {
-  'data-state'?: 'active'
-}
+export type TabsTriggerProps<T extends ElementType = 'button'> = PolymorphicProps<
+  T,
+  { 'data-state'?: 'active' }
+>
 
-export function TabsTrigger({ className, role = 'tab', ...props }: TabsTriggerProps) {
-  return (
-    <button role={role} className={cn('sheerly-tabs-trigger', className)} {...props} />
-  )
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `button`).
+ */
+export function TabsTrigger<T extends ElementType = 'button'>({
+  as,
+  className,
+  ...props
+}: TabsTriggerProps<T>) {
+  const Tag = as ?? 'button'
+  return <Tag role="tab" className={cn('sheerly-tabs-trigger', className)} {...props} />
 }
 
-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>