@womp/kookie-ui 0.21.0 → 0.22.0

package/README.md

@@ -59,11 +59,13 @@ already load.
 
 Kookie UI is a fork of [Radix Themes](https://radix-ui.com/themes) that extends it into a full design system. While Radix provided excellent building blocks, Kookie UI codifies the patterns and rules that make interfaces feel consistent and systematic.
 
+`MessageScroller` is Kookie's surface over shadcn/ui's [Message Scroller](https://ui.shadcn.com) primitive (`@shadcn/react`, MIT); the scrolling behaviour is shadcn's.
+
 ### Key Features
 
 - **Systematic Design Tokens** - 12-point progressions for spacing, radius, and shadows with predictable steps
-- **Universal Material System** - Every component understands translucency vs. solidity with theme-level defaults and per-component overrides
-- **Consistent Sizing** - Cards, buttons, dropdowns, selects, and avatars all follow the same scale
+- **Solid surfaces** - Every surface is solid; there is no translucency or backdrop blur
+- **Shared Size Steps** - Controls share one set of size steps
 - **No motion** - State changes are instant; only busy indicators move
 - **Enhanced Accessibility** - Native tooltip support, stricter aria-label enforcement, and improved keyboard navigation
 - **Layout Patterns** - Shells, sidebars, panels, and toolbars that work together predictably
@@ -213,15 +215,15 @@ import '@womp/kookie-ui/layout.css'; // Layout utilities
 
 ## Requirements
 
-- React 16.8+ through React 19
+- React 18 or 19 (`MessageScroller` needs React 19)
 - Node.js 16+ (for development)
 - TypeScript support built-in
 
 ```json
 {
   "peerDependencies": {
-    "react": "16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-    "react-dom": "16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+    "react": "^18.0 || ^19.0",
+    "react-dom": "^18.0 || ^19.0"
   }
 }
 ```
@@ -297,7 +299,6 @@ Kookie UI uses a comprehensive theming system with:
 
 - **Accent Colors** - Primary brand colors (blue, green, orange, etc.)
 - **Gray Colors** - Neutral color scales (gray, mauve, slate, etc.)
-- **Material System** - Translucent vs. solid surfaces
 - **Size Scales** - Consistent sizing across components
 - **Spacing System** - 12-point spacing progression
 - **Typography** - Font scales and weights

package/codemods/_shared.py

@@ -0,0 +1,314 @@
+"""
+Helpers the Kookie UI codemods share: which files to visit, and a small JavaScript/JSX scanner
+that tells code apart from strings, comments, regex literals and JSX text.
+"""
+import os
+import re
+
+# Skipped at any depth.
+SKIP_ANYWHERE = {'node_modules', '.next', '.git'}
+# Skipped only when they sit directly inside a folder given on the command line, where they are
+# build output. A source folder deeper down named build or dist (src/app/build) is visited.
+SKIP_TOP = {'dist', 'build'}
+
+
+def files(targets, extensions):
+    """Yield every file under the given folders (or the given files) that ends in one of extensions."""
+    for target in targets:
+        if os.path.isfile(target):
+            if target.endswith(extensions):
+                yield target
+            continue
+        root_depth = os.path.abspath(target).rstrip(os.sep).count(os.sep)
+        for folder, dirs, names in os.walk(target):
+            top = os.path.abspath(folder).rstrip(os.sep).count(os.sep) == root_depth
+            dirs[:] = sorted(d for d in dirs if d not in SKIP_ANYWHERE and not (top and d in SKIP_TOP))
+            for name in sorted(names):
+                if name.endswith(extensions):
+                    yield os.path.join(folder, name)
+
+
+IDENT = re.compile(r'[A-Za-z_$][\w$]*')
+TAG_NAME = re.compile(r'[A-Za-z_$][\w$.:-]*')
+ATTR_NAME = re.compile(r'[A-Za-z_$][\w$:.-]*')
+NUMBER = re.compile(r'\d[\w.]*')
+# After these words an expression starts, so `<` opens JSX and `/` opens a regex.
+EXPR_KEYWORDS = {
+    'return', 'typeof', 'case', 'yield', 'await', 'in', 'of', 'new', 'delete', 'void', 'throw',
+    'else', 'do', 'instanceof', 'default', 'extends',
+}
+
+
+class Scan:
+    """
+    Walks a .ts/.tsx/.js/.jsx source once and records, with offsets:
+
+    - idents: (start, end, name, object) for every identifier in code, where object is the
+      identifier before a `.` (`K` in `K.Badge`) or None
+    - tags: (start, end, name, closing) for every JSX tag name, closing for `</Name>`
+    - attrs: (tag_index, name, value_start, value_end) for every attribute written on a tag
+
+    Strings, template text, comments, regex literals and JSX text record nothing.
+    """
+
+    def __init__(self, text, jsx=True, run=True):
+        self.t = text
+        self.n = len(text)
+        self.jsx = jsx
+        self.idents = []
+        self.tags = []
+        self.attrs = []
+        if run:
+            self.code(0, False)
+
+    @classmethod
+    def elements(cls, text, pattern):
+        """Scan only the JSX elements that start where pattern matches (for .mdx, which is not JS)."""
+        scan = cls(text, True, run=False)
+        for m in pattern.finditer(text):
+            scan.element(m.start())
+        return scan
+
+    # --- code ---------------------------------------------------------------------------
+
+    def code(self, i, stop):
+        t, n = self.t, self.n
+        depth = 0
+        expr = True  # whether the next token starts an expression
+        while i < n:
+            c = t[i]
+            if c in ' \t\r\n':
+                i += 1
+            elif c == '/' and t.startswith('//', i):
+                j = t.find('\n', i)
+                i = n if j < 0 else j
+            elif c == '/' and t.startswith('/*', i):
+                j = t.find('*/', i + 2)
+                i = n if j < 0 else j + 2
+            elif c in '"\'':
+                i = self.string(i)
+                expr = False
+            elif c == '`':
+                i = self.template(i)
+                expr = False
+            elif c == '/' and expr:
+                i = self.regex(i)
+                expr = False
+            elif c == '<' and expr and self.jsx:
+                end = self.element(i)
+                if end is None:
+                    i += 1
+                    expr = True
+                else:
+                    i = end
+                    expr = False
+            elif c == '{':
+                depth += 1
+                i += 1
+                expr = True
+            elif c == '}':
+                if depth == 0 and stop:
+                    return i
+                depth -= 1
+                i += 1
+                expr = True
+            elif c in ')]':
+                i += 1
+                expr = False
+            elif c.isdigit():
+                i = NUMBER.match(t, i).end()
+                expr = False
+            elif c.isalpha() or c in '_$':
+                m = IDENT.match(t, i)
+                name = m.group(0)
+                self.idents.append((i, m.end(), name, self.object_before(i)))
+                i = m.end()
+                expr = name in EXPR_KEYWORDS
+            else:
+                i += 1
+                expr = True
+        return n
+
+    def object_before(self, i):
+        t = self.t
+        k = i - 1
+        while k >= 0 and t[k] in ' \t\r\n':
+            k -= 1
+        if k < 0 or t[k] != '.' or (k > 0 and t[k - 1] == '.'):
+            return None
+        k -= 1
+        if k >= 0 and t[k] == '?':
+            k -= 1
+        while k >= 0 and t[k] in ' \t\r\n':
+            k -= 1
+        end = k + 1
+        while k >= 0 and (t[k].isalnum() or t[k] in '_$'):
+            k -= 1
+        return t[k + 1:end] or None
+
+    def string(self, i):
+        t, n, q = self.t, self.n, self.t[i]
+        i += 1
+        while i < n and t[i] != q:
+            if t[i] == '\\':
+                i += 1
+            elif t[i] == '\n':
+                break
+            i += 1
+        return i + 1
+
+    def template(self, i):
+        t, n = self.t, self.n
+        i += 1
+        while i < n and t[i] != '`':
+            if t[i] == '\\':
+                i += 2
+            elif t.startswith('${', i):
+                i = self.code(i + 2, True) + 1
+            else:
+                i += 1
+        return i + 1
+
+    def regex(self, i):
+        t, n = self.t, self.n
+        i += 1
+        klass = False
+        while i < n and t[i] != '\n':
+            if t[i] == '\\':
+                i += 2
+                continue
+            if t[i] == '[':
+                klass = True
+            elif t[i] == ']':
+                klass = False
+            elif t[i] == '/' and not klass:
+                i += 1
+                while i < n and t[i].isalpha():
+                    i += 1
+                return i
+            i += 1
+        return i
+
+    # --- JSX ----------------------------------------------------------------------------
+
+    def element(self, i):
+        """Scan a JSX element starting at `<`. Returns the index after it, or None (not JSX)."""
+        marks = (len(self.idents), len(self.tags), len(self.attrs))
+        end = self._element(i)
+        if end is None:
+            del self.idents[marks[0]:]
+            del self.tags[marks[1]:]
+            del self.attrs[marks[2]:]
+        return end
+
+    def ws(self, j):
+        while j < self.n and self.t[j] in ' \t\r\n':
+            j += 1
+        return j
+
+    def _element(self, i):
+        t, n = self.t, self.n
+        j = self.ws(i + 1)
+        if j < n and t[j] == '>':
+            name, tag = '', None
+        else:
+            m = TAG_NAME.match(t, j)
+            if not m:
+                return None
+            name = m.group(0)
+            tag = len(self.tags)
+            self.tags.append((j, m.end(), name, False))
+            j = m.end()
+            # `<T,>` and `<T extends X>` are TypeScript generics, not JSX.
+            k = self.ws(j)
+            if k < n and t[k] == ',' or t.startswith('extends', k) and not TAG_NAME.match(t, k + 7):
+                return None
+        while True:
+            j = self.ws(j)
+            if j >= n:
+                return None
+            c = t[j]
+            if t.startswith('/>', j):
+                return j + 2
+            if c == '>':
+                return self.children(j + 1)
+            if c == '{':
+                k = self.code(j + 1, True)
+                if k >= n:
+                    return None
+                j = k + 1
+            elif c.isalpha() or c in '_$':
+                m = ATTR_NAME.match(t, j)
+                attr = m.group(0)
+                j = self.ws(m.end())
+                if j < n and t[j] == '=':
+                    j = self.ws(j + 1)
+                    start = j
+                    if j < n and t[j] in '"\'':
+                        k = t.find(t[j], j + 1)
+                        if k < 0:
+                            return None
+                        j = k + 1
+                    elif j < n and t[j] == '{':
+                        k = self.code(j + 1, True)
+                        if k >= n:
+                            return None
+                        j = k + 1
+                    elif j < n and t[j] == '<':
+                        k = self.element(j)
+                        if k is None:
+                            return None
+                        j = k
+                    else:
+                        return None
+                    if tag is not None:
+                        self.attrs.append((tag, attr, start, j))
+            else:
+                return None
+
+    def children(self, j):
+        t, n = self.t, self.n
+        while j < n:
+            c = t[j]
+            if c == '<':
+                k = self.ws(j + 1)
+                if k < n and t[k] == '/':
+                    k = self.ws(k + 1)
+                    m = TAG_NAME.match(t, k)
+                    if m:
+                        self.tags.append((k, m.end(), m.group(0), True))
+                        k = m.end()
+                    k = self.ws(k)
+                    if k >= n or t[k] != '>':
+                        return None
+                    return k + 1
+                end = self.element(j)
+                if end is None:
+                    return None
+                j = end
+            elif c == '{':
+                k = self.code(j + 1, True)
+                if k >= n:
+                    return None
+                j = k + 1
+            else:
+                j += 1
+        return None
+
+
+def apply(text, edits):
+    """Apply (start, end, replacement) edits that do not overlap."""
+    out = []
+    last = 0
+    for start, end, new in sorted(edits):
+        if start < last:
+            continue
+        out.append(text[last:start])
+        out.append(new)
+        last = end
+    out.append(text[last:])
+    return ''.join(out)
+
+
+def line_of(text, offset):
+    return text.count('\n', 0, offset) + 1

package/codemods/components-0.21.py

@@ -4,21 +4,29 @@ Kookie UI 0.21 components codemod.
 The component list follows v2. Four names merge into others. This rewrites, in place:
 
 - IconButton -> Button iconOnly, ToggleIconButton -> Toggle iconOnly, ToggleButton -> Toggle,
-  Badge -> Chip: JSX tags, the import from @womp/kookie-ui, other references to the
-  imported name, and the Props types (IconButtonProps -> ButtonProps, BadgeProps -> ChipProps,
-  ToggleButtonProps and ToggleIconButtonProps -> ToggleProps) (.ts/.tsx/.jsx/.mdx)
+  Badge -> Chip: JSX tags (also under an alias or a namespace import, `<K.Badge>`), the import
+  from @womp/kookie-ui, other code references to the imported name, and the Props types
+  (IconButtonProps -> ButtonProps, BadgeProps -> ChipProps, ToggleButtonProps and
+  ToggleIconButtonProps -> ToggleProps) (.ts/.tsx/.js/.jsx/.mdx)
 - .rt-Badge -> .rt-Chip and .rt-IconButton -> .rt-Button[data-icon-only] in .css/.scss
 
+Strings, comments and JSX text are left alone. A reference to IconButton or ToggleIconButton
+outside a JSX tag (`const Comp = IconButton`, or `const Comp = IB` under an alias) is printed: it
+needs `iconOnly` where it renders, which only a person can add. A direct name is left as it is, so
+TypeScript flags it; an alias still type-checks, so the printed line is the only notice.
+
 It only renames. Dropped components, margin props on leaf components and icon-only buttons
 named by visible text need a person: see MIGRATION.md.
 
-Usage: python3 components-0.21.py <folder> [<folder> ...]   Safe to run twice.
+Usage: python3 components-0.21.py <folder|file> [...]   Safe to run twice.
 """
-import glob
 import os
 import re
 import sys
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _shared import Scan, apply, files, line_of  # noqa: E402
+
 # old name -> (new name, adds iconOnly)
 RENAME = {
     'IconButton': ('Button', True),
@@ -32,25 +40,28 @@ TYPES = {
     'ToggleButtonProps': 'ToggleProps',
     'BadgeProps': 'ChipProps',
 }
-IMPORT = re.compile(r'import(\s+type)?\s*\{([^{}]*)\}\s*from\s*([\'"])@womp/kookie-ui\3')
+SOURCE = r'([\'"])@womp/kookie-ui\3'
+IMPORT = re.compile(r'import(\s+type)?\s*\{([^{}]*)\}\s*from\s*' + SOURCE)
+NAMESPACE = re.compile(r'import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*([\'"])@womp/kookie-ui\2')
 CSS = [
     (re.compile(r'\.rt-Badge(?![\w-])'), '.rt-Chip'),
     (re.compile(r'\.rt-IconButton(?![\w-])'), '.rt-Button[data-icon-only]'),
 ]
-SKIP = ('node_modules', '/.next/', '/dist/', '/build/')
-
-
-def word(name):
-    return re.compile(r'(?<![\w$.-])' + name + r'(?![\w$-])')
+EXT = ('.css', '.scss', '.ts', '.tsx', '.js', '.jsx', '.mdx')
 
 
 def imported(text):
-    names = set()
+    """Local name -> the name it was imported as, for every named import from Kookie."""
+    names = {}
     for m in IMPORT.finditer(text):
         for part in m.group(2).split(','):
-            bits = part.replace('type ', ' ').split()
+            bits = part.split()
+            if bits and bits[0] == 'type':
+                bits = bits[1:]
             if len(bits) == 1:
-                names.add(bits[0])
+                names[bits[0]] = bits[0]
+            elif len(bits) == 3 and bits[1] == 'as':
+                names[bits[2]] = bits[0]
     return names
 
 
@@ -72,21 +83,66 @@ def fix_import(m):
     return 'import%s {%s} from %s@womp/kookie-ui%s' % (m.group(1) or '', body, m.group(3), m.group(3))
 
 
-def rewrite_jsx(text, mdx):
+def tag_target(name, names, spaces):
+    """The original Kookie name a JSX tag refers to and the tag's new name, or (None, None)."""
+    if '.' in name:
+        space, _, member = name.partition('.')
+        if space in spaces and member in RENAME:
+            return member, space + '.' + RENAME[member][0]
+        return None, None
+    original = names.get(name)
+    if original in RENAME:
+        return original, RENAME[original][0] if name == original else name
+    return None, None
+
+
+def rewrite_code(text, jsx, path='<text>', warn=None):
     names = imported(text)
-    for old, (new, icon_only) in RENAME.items():
-        if old not in names and not mdx:
+    spaces = {m.group(1) for m in NAMESPACE.finditer(text)}
+    if not (set(names.values()) & (set(RENAME) | set(TYPES))) and not spaces:
+        return text
+    skip = [(m.start(), m.end()) for m in IMPORT.finditer(text)]
+    scan = Scan(text, jsx)
+    edits = []
+    for start, end, name, closing in scan.tags:
+        original, new = tag_target(name, names, spaces)
+        if original is None:
+            continue
+        flag = ' iconOnly' if RENAME[original][1] and not closing else ''
+        edits.append((start, end, new + flag))
+    for start, end, name, obj in scan.idents:
+        if any(a <= start < b for a, b in skip):
+            continue
+        if obj is None and name in names:
+            original = names[name]
+        elif obj is not None and obj in spaces:
+            original = name
+        else:
             continue
+        # An alias (`IconButton as IB`) keeps its local name: the import rename moves it.
+        aliased = obj is None and name != original
+        if original in TYPES:
+            if not aliased:
+                edits.append((start, end, TYPES[original]))
+        elif original in RENAME:
+            new, icon_only = RENAME[original]
+            if icon_only:
+                if warn is not None:
+                    todo = 'add iconOnly' if aliased else 'rename it to %s and add iconOnly' % new
+                    warn('%s:%d: %s used outside a JSX tag; %s where it renders' % (path, line_of(text, start), name, todo))
+                continue
+            if not aliased:
+                edits.append((start, end, new))
+    text = apply(text, edits)
+    return IMPORT.sub(fix_import, text)
+
+
+def rewrite_mdx(text):
+    for old, (new, icon_only) in RENAME.items():
         flag = ' iconOnly' if icon_only else ''
         text = re.sub(r'<' + old + r'(?![\w$.-])', '<' + new + flag, text)
         text = re.sub(r'</' + old + r'\s*>', '</' + new + '>', text)
-    for old, new in TYPES.items():
-        if old in names:
-            text = word(old).sub(new, text)
-    for old, (new, _) in RENAME.items():
-        if old in names:
-            text = word(old).sub(new, text)
-    return IMPORT.sub(fix_import, text) if names & (set(RENAME) | set(TYPES)) else text
+    return IMPORT.sub(fix_import, text)
 
 
 def rewrite_css(text):
@@ -95,25 +151,25 @@ def rewrite_css(text):
     return text
 
 
-def main(folders):
+def rewrite(text, path, warn=None):
+    if path.endswith(('.css', '.scss')):
+        return rewrite_css(text)
+    if path.endswith('.mdx'):
+        return rewrite_mdx(text)
+    return rewrite_code(text, not path.endswith('.ts'), path, warn)
+
+
+def main(targets):
     changed = 0
-    for folder in folders:
-        for path in glob.glob(os.path.join(folder, '**', '*'), recursive=True):
-            if not os.path.isfile(path) or any(s in path for s in SKIP):
-                continue
-            if path.endswith(('.css', '.scss')):
-                fn = rewrite_css
-            elif path.endswith(('.ts', '.tsx', '.jsx', '.mdx')):
-                fn = lambda t, mdx=path.endswith('.mdx'): rewrite_jsx(t, mdx)
-            else:
-                continue
-            with open(path) as f:
-                before = f.read()
-            after = fn(before)
-            if after != before:
-                with open(path, 'w') as f:
-                    f.write(after)
-                changed += 1
+    warn = lambda message: print(message, file=sys.stderr)
+    for path in files(targets, EXT):
+        with open(path) as f:
+            before = f.read()
+        after = rewrite(before, path, warn)
+        if after != before:
+            with open(path, 'w') as f:
+                f.write(after)
+            changed += 1
     print('%d files rewritten' % changed)
 
 

package/codemods/names-0.22.py

@@ -0,0 +1,65 @@
+"""
+Kookie UI 0.22 names codemod.
+
+Class names and private variables move from Radix Themes' prefix to Kookie's, as in v2:
+`rt-` -> `kui-` (classes like rt-Button, rt-r-size-2, and variables like --rt-shell-gap) and the
+root class `radix-themes` -> `kui-theme`. The neutral scale's variables move from --gray-N to
+--neutral-N (the `color="gray"` prop value does not change). The page and surface colours take
+v2's names: --color-background -> --color-page, and --color-panel(-solid), --color-surface-solid
+and --color-dialog(-solid) -> --color-surface. The translucent tokens 0.17 removed
+(--color-panel-translucent, --color-surface-translucent, --color-dialog-translucent) also become
+--color-surface, the solid colour they fell back to.
+
+Usage: python3 names-0.22.py <folder|file> [...]   Safe to run twice.
+"""
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _shared import files  # noqa: E402
+
+PREFIX = re.compile(r'(?<![A-Za-z0-9_])rt-(?=[A-Za-z-])')
+ROOT = re.compile(r'(?<![A-Za-z0-9_@/])radix-themes(?![A-Za-z0-9_-])')
+NEUTRAL = re.compile(r'--gray-(a?\d+\b|contrast\b|surface\b|indicator\b|track\b|ink\b|ink-faint\b|ink-muted\b)')
+COLORS = [
+    ('--color-panel-solid', '--color-surface'),
+    ('--color-surface-solid', '--color-surface'),
+    ('--color-dialog-solid', '--color-surface'),
+    ('--color-panel-translucent', '--color-surface'),
+    ('--color-surface-translucent', '--color-surface'),
+    ('--color-dialog-translucent', '--color-surface'),
+    ('--color-panel', '--color-surface'),
+    ('--color-dialog', '--color-surface'),
+    ('--color-background', '--color-page'),
+]
+EXT = ('.css', '.scss', '.ts', '.tsx', '.js', '.jsx', '.cjs', '.mjs', '.mdx', '.html')
+
+
+def rewrite(text, neutral=True):
+    text = PREFIX.sub('kui-', text)
+    text = ROOT.sub('kui-theme', text)
+    if neutral:
+        text = NEUTRAL.sub(lambda m: '--neutral-' + m.group(1), text)
+    for old, new in COLORS:
+        text = re.sub(re.escape(old) + r'(?![\w-])', new, text)
+    return text
+
+
+def main(targets):
+    changed = 0
+    for path in files(targets, EXT):
+        with open(path) as f:
+            before = f.read()
+        after = rewrite(before)
+        if after != before:
+            with open(path, 'w') as f:
+                f.write(after)
+            changed += 1
+    print('%d files rewritten' % changed)
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    main(sys.argv[1:])