shelving 1.319.1 → 1.321.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/docs/guides/building-with-shelving.md +26 -0
  2. package/docs/llms-full.txt +752 -265
  3. package/docs/ui/BackButton.md +75 -0
  4. package/docs/ui/BackButtonProps.md +21 -0
  5. package/docs/ui/ClickableProps.md +0 -2
  6. package/docs/ui/FADE_TRANSITION_CLASS.md +9 -0
  7. package/docs/ui/FadeTransition.md +13 -0
  8. package/docs/ui/Head.md +2 -2
  9. package/docs/ui/HorizontalTransition.md +21 -5
  10. package/docs/ui/LinkClickable.md +0 -1
  11. package/docs/ui/Meta.md +3 -1
  12. package/docs/ui/Navigation.md +93 -37
  13. package/docs/ui/NavigationEntryState.md +22 -0
  14. package/docs/ui/NavigationPosition.md +24 -0
  15. package/docs/ui/NavigationPositionContext.md +8 -0
  16. package/docs/ui/NavigationProps.md +12 -2
  17. package/docs/ui/NavigationStore/back.md +6 -4
  18. package/docs/ui/NavigationStore/forward.md +6 -2
  19. package/docs/ui/NavigationStore/history.md +15 -0
  20. package/docs/ui/NavigationStore/listen.md +14 -0
  21. package/docs/ui/NavigationStore/replace.md +15 -0
  22. package/docs/ui/NavigationStore.md +100 -19
  23. package/docs/ui/RouteCache.md +72 -36
  24. package/docs/ui/RouteCacheProps.md +3 -3
  25. package/docs/ui/Router.md +4 -2
  26. package/docs/ui/SLIDE_DOWN_TRANSITION_CLASS.md +9 -0
  27. package/docs/ui/SLIDE_LEFT_TRANSITION_CLASS.md +9 -0
  28. package/docs/ui/SLIDE_RIGHT_TRANSITION_CLASS.md +9 -0
  29. package/docs/ui/SLIDE_UP_TRANSITION_CLASS.md +9 -0
  30. package/docs/ui/StackButton.md +64 -0
  31. package/docs/ui/StackButtonProps.md +21 -0
  32. package/docs/ui/VerticalTransition.md +21 -5
  33. package/docs/ui/mergeMeta.md +2 -1
  34. package/docs/ui.md +18 -10
  35. package/package.json +1 -1
  36. package/ui/button/Clickable.d.ts +1 -3
  37. package/ui/button/Clickable.js +2 -2
  38. package/ui/button/Clickable.tsx +0 -4
  39. package/ui/dialog/Dialog.d.ts +0 -1
  40. package/ui/dialog/Dialog.js +2 -2
  41. package/ui/dialog/Dialog.tsx +2 -2
  42. package/ui/notice/NoticesTransition.module.css +1 -1
  43. package/ui/page/Head.d.ts +2 -2
  44. package/ui/page/Head.js +9 -8
  45. package/ui/page/Head.tsx +8 -6
  46. package/ui/router/BackButton.d.ts +22 -0
  47. package/ui/router/BackButton.js +19 -0
  48. package/ui/router/BackButton.md +47 -0
  49. package/ui/router/BackButton.tsx +34 -0
  50. package/ui/router/Navigation.d.ts +22 -12
  51. package/ui/router/Navigation.js +67 -51
  52. package/ui/router/Navigation.md +84 -27
  53. package/ui/router/Navigation.test.tsx +27 -7
  54. package/ui/router/Navigation.tsx +90 -53
  55. package/ui/router/NavigationContext.d.ts +9 -1
  56. package/ui/router/NavigationContext.js +9 -0
  57. package/ui/router/NavigationContext.tsx +11 -1
  58. package/ui/router/NavigationStore.d.ts +126 -19
  59. package/ui/router/NavigationStore.js +301 -30
  60. package/ui/router/NavigationStore.md +82 -9
  61. package/ui/router/NavigationStore.test.ts +384 -0
  62. package/ui/router/NavigationStore.tsx +347 -30
  63. package/ui/router/RouteCache.d.ts +15 -22
  64. package/ui/router/RouteCache.js +36 -47
  65. package/ui/router/RouteCache.md +59 -16
  66. package/ui/router/RouteCache.tsx +55 -62
  67. package/ui/router/Router.d.ts +2 -1
  68. package/ui/router/Router.js +9 -14
  69. package/ui/router/Router.md +2 -1
  70. package/ui/router/Router.tsx +9 -20
  71. package/ui/router/StackButton.d.ts +24 -0
  72. package/ui/router/StackButton.js +35 -0
  73. package/ui/router/StackButton.md +34 -0
  74. package/ui/router/StackButton.tsx +44 -0
  75. package/ui/router/index.d.ts +2 -2
  76. package/ui/router/index.js +2 -2
  77. package/ui/router/index.ts +2 -2
  78. package/ui/transition/FadeTransition.d.ts +9 -1
  79. package/ui/transition/FadeTransition.js +12 -2
  80. package/ui/transition/FadeTransition.md +13 -0
  81. package/ui/transition/{FadeTransition.css → FadeTransition.module.css} +9 -2
  82. package/ui/transition/FadeTransition.tsx +13 -2
  83. package/ui/transition/HorizontalTransition.d.ts +18 -1
  84. package/ui/transition/HorizontalTransition.js +21 -2
  85. package/ui/transition/HorizontalTransition.md +21 -5
  86. package/ui/transition/{HorizontalTransition.css → HorizontalTransition.module.css} +17 -5
  87. package/ui/transition/HorizontalTransition.tsx +30 -2
  88. package/ui/transition/VerticalTransition.d.ts +18 -1
  89. package/ui/transition/VerticalTransition.js +21 -2
  90. package/ui/transition/VerticalTransition.md +21 -5
  91. package/ui/transition/{VerticalTransition.css → VerticalTransition.module.css} +17 -5
  92. package/ui/transition/VerticalTransition.tsx +25 -2
  93. package/ui/util/meta.d.ts +4 -1
  94. package/ui/util/meta.ts +4 -1
  95. package/docs/ui/NavigationStore/redirect.md +0 -12
  96. package/docs/ui/RouteConfig.md +0 -75
  97. package/docs/ui/RouteConfigProps.md +0 -24
  98. package/docs/ui/RouteContext.md +0 -6
  99. package/docs/ui/RouteState.md +0 -30
  100. package/ui/router/RouteConfig.d.ts +0 -28
  101. package/ui/router/RouteConfig.js +0 -30
  102. package/ui/router/RouteConfig.md +0 -42
  103. package/ui/router/RouteConfig.tsx +0 -44
  104. package/ui/router/RouteContext.d.ts +0 -22
  105. package/ui/router/RouteContext.js +0 -8
  106. package/ui/router/RouteContext.tsx +0 -26
@@ -693,6 +693,32 @@ If every file in that list is in the right place, the client and server share on
693
693
 
694
694
  ## Upgrade notes
695
695
 
696
+ ### Tab stacks in `<Navigation>`
697
+
698
+ `<Navigation>` now keeps one stack of pages for each tab, like a phone app. It uses the browser [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API). Some names and props changed. To upgrade an app:
699
+
700
+ 1. **Rename `redirect()` to `replace()`.** Change each `nav.redirect(url)` to `nav.replace(url)`. It does the same thing: it changes the URL of the current page with no new history entry and no slide.
701
+ 2. **Change the `back` prop to a class.** The `back` prop on `<Button>` and `<Link>` is removed, and so is the `data-back` attribute. Change `<Button href="/profile" back>` to `<Button href="/profile" className="back">`. For a page-header back button, use `<BackButton href="/profile"/>` (see step 6).
702
+ 3. **Remove `<RouteConfig>`.** `<RouteConfig>` and `RouteContext` are removed.
703
+ - `<RouteConfig path>` kept a page mounted for its tabs (for example `/dave/{tab}`). Instead, add `className="replace"` to each in-page tab link: `<Button href="/dave/posts" className="replace">Posts</Button>`. A replace keeps the same page mounted, with no slide and no new history entry.
704
+ - `<RouteConfig cache={false}>` unmounted a create form when you left it. Instead, clear the form after a successful submit: change the `key` of the `<Form>`, or call `form.reset()` on a plain HTML form. See `<RouteCache>` for an example.
705
+ 4. **Canonical URLs.** `<Head>` no longer writes browser history itself. When a page renders a `<Head>` with a `url` that is not the current URL, `<Head>` calls `NavigationStore.replace()`. You do not need to change anything, but do not also call `window.history.replaceState()` for it.
706
+ 5. **Add stacks (optional).** For an app with a tab bar, set `stacks` on `<Navigation>` to the root path of each tab, in tab order: `<Navigation stacks={["/home", "/discover", "/profile"]}>`. Each link then opens a new page in the current tab, wherever it points. Set `stack` on `<Navigation>` to the stack the app opens in. With no `stack`, the app opens in the `/` stack, which is unstacked: no tab is selected until the user taps a tab, or the app names a stack. Deep links and login pages are unstacked. A login page calls `nav.replace("/home", "/home")` to send the user into the Home tab.
707
+ 6. **Use the new buttons (optional).**
708
+ - `<StackButton stack="/home">` is a tab bar button. It goes to the page you left in that tab, goes back to the tab's root when you are already in it, and scrolls to the top at the root.
709
+ - `<BackButton href="/home"/>` goes back to the page before this one in the current tab, or to `href` when there is none.
710
+ 7. **Move the page transition outside `<RouteCache>`.** Put `<HorizontalTransition>` (or any page `<Transition>`) around the `<RouteCache>`, not inside it around each page. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
711
+ 8. **Check pages that change URL for the same component.** `<RouteCache>` now keys each page by its stack and depth, not by its path. A replace from `/post/1` to `/post/2` keeps the same component mounted with its state. If the page must reset, wrap its content in an element with `key={id}`.
712
+ 9. **Know the fallback.** Without the Navigation API (older browsers), links still work with no page reload, but there are no stacks, no slides and no page cache. `<StackButton>` and `<BackButton>` become plain links.
713
+
714
+ What changes for users:
715
+
716
+ - Each tab remembers the page you left it on, and its back button goes back within that tab.
717
+ - The browser back button walks the history as before, across tabs. The page slides the right way.
718
+ - When you go back from a page, it leaves the cache. So the browser forward button then shows that page fresh, from the top.
719
+
720
+ See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
721
+
696
722
  ### From `CacheDBProvider` to `HydratingAPIProvider`
697
723
 
698
724
  `CacheDBProvider` and the paging in `QueryStore` are removed. To upgrade an app: