New: sharing state core concept! by bholmesdev · Pull Request #934 · withastro/docs

bholmesdev · 2022-07-05T22:37:08Z

What kind of changes does this PR include?

Minor content fixes (broken links, typos, etc.)
New or updated content
Translated content
Changes to the docs site code
Something else!

Description

Add new Tabs Preact component for tab views across our docs. This includes:
- A UIFrameworkTabs utility component for easily embedding UI framework comparisons
- A generic Tabs component for any tab view you could want, based on slots
Add a new core concept page: Sharing State. This includes:
- A primer on what user problem this page addresses
- Why nanostores (with a brief comparison to Svelte stores)
- A usage example that will mirror one of our astro.new examples soon
- A walkthrough on nanostore "atoms"
- A walkthrough on nanostore "maps"
Add LoopingVideo.astro utility for video embeds

sharing-state-docs.mov

netlify · 2022-07-05T22:37:12Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`e175c1b`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/62c897ad6753f40008657bf7
😎 Deploy Preview	https://deploy-preview-934--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

crutchcorn · 2022-07-05T23:07:25Z

Awesome work! 🎉

Something I'm noticing is the "Jump when tab switch" due to a mismatch of content length between tabs. This leads to a jarring experience that, when I implemented it for my blog, lead to a lot of errant bug reports being filed.

Here's a GIF of this in an extreme example:

Screen.Recording.2022-06-19.At.2.41.02.Pm-1.mp4

To fix this, I effectively:

Attached a unique ID to each tab header
On tab selection change, added a setTimeout(() => {}, 0) to queue a microtask to jump to the tab header using scrollIntoView

Here's a PR that I wrote to fix this problem:

playfulprogramming/playfulprogramming#374

yanthomasdev

Amazing work Ben "Tabs" H! I left a few suggestions for you 🙌

I also verified the Tabs component accessibility with NVDA and it is perfect for me 👌

zadeviggers · 2022-07-06T01:37:01Z

This looks great! I did notice that on mobile (android firefox) some of the tabs overflow off the page and you can't scroll them to see the cut off content.
I also think it might be good to touch on the Solid stores a bit more in depth since the page is about sharing state in general, not nanostores specificaly (unless I'm very much mistaken, in which case I apologise).
Overall this is a very well written page!

natemoo-re

Looking great! Two small suggestions, neither blocking.

bholmesdev · 2022-07-06T20:58:57Z

@zadeviggers horizontal scrolling added!

bholmesdev · 2022-07-06T21:28:30Z

@zadeviggers Also added a callout on solid stores for shared state. Let me know if these instructions make sense!
e8123d1

bholmesdev · 2022-07-06T21:29:13Z

@crutchcorn addressed!

zadeviggers · 2022-07-06T21:39:37Z

Looks great @bholmesdev!

sarah11918 · 2022-07-06T21:45:09Z

Just a quick note before I check the sites I have queued up to read re: "using emoji as end punctuation".... BEN...

I'm not sure this page fits in the "Core Concepts" section, and I'm leaning towards it belonging in "Features" rather than "Basics" (as the pages are structured now). I'm curious to hear others' thoughts on this.

The material that Fred is drafting in #893 is more overall description/philosophy of principle, and not technical walkthroughs. "Basics" are (right now) for things that are inherent to understanding an Astro project: file structure, components, pages/routing etc. and "Features" (formerly "Guides") are "Things you'd expect a website to have/do, and here's how you'd do that in/with your Astro site." The Basics briefly show some essential code patterns, but the Features will demonstrate the code required to achieve ... a feature. This feels like the latter to me? Thoughts?

hippotastic · 2022-07-06T23:14:53Z

I love the general idea of this! However, switching any of the tabs in the Netlify preview doesn't work on iOS Safari for me.

hippotastic · 2022-07-07T16:15:07Z

It works well in iOS Safari now after your updates. Great job!

FredKSchott · 2022-07-07T19:23:02Z

Like @sarah11918 said, this is more of a Guide than a technical concept essential to the very core of Astro :) Place it with the other features in the sidebar, and we can experiment with renaming that heading to "Guides" if it makes more sense.

delucis

Hey Ben! Well isn’t this fantab ulous! Thank you. Sorry it took me a while to get you a review.

I’ve mostly focused on the technical side of things as I’m sure Sarah will have things to say about the content, and I don’t want to overwhelm you with too many editors.

sarah11918

Whew! Ben! Sorry, this took a little long because besides just a proofreading edit, one thing I look closely for is internal consistency both within the page and within the Docs as a whole. And, this, while delightful, takes both a slightly different tone, and a different level of technical explanation than most other pages in the docs. So, it did also require a bit of double-checking for "comps" around the site... all while reading the comments in Discord, seeing the file update underneath me...

So, here are my thoughts! Thanks for being patient! And thanks as always for contributing to the docs.. and uniting so many people into one PR. It's great to see so many people get involved!

sarah11918 · 2022-07-07T22:15:17Z

+
+"Typical" UI frameworks like React, Vue, or Svelte may encourage ["context" providers](https://reactjs.org/docs/context.html) for other components to consume. But when [partially hydrating components](/en/core-concepts/framework-components/#hydrating-interactive-components) within Astro or Markdown, you cannot use these context wrappers 😳
+
+We'll need a different solution to create shared stores your components can read and write from: [**nanostores**](https://github.com/nanostores/nanostores).


Suggested change

We'll need a different solution to create shared stores your components can read and write from: [**nanostores**](https://github.com/nanostores/nanostores).

We'll need a different solution to create shared stores your components can read from and write to: [**nanostores**](https://github.com/nanostores/nanostores).

nit: prepositions

Also, this does somewhat frame nanostores as the solution (even though you back off on that below).

An alternative, if you cared, is: "Astro suggests a different solution to ..."

Then, the question "Why nanostores?" flows well, as if to answer, "Why does Astro recommend that?". The list of alternatives following that again fits with Astro "suggesting" but not requiring, and demonstrating other options.

Updated to the clearer: "Astro recommends a different solution for shared client-side storage"

sarah11918 · 2022-07-07T23:12:28Z

+</Fragment>
+</UIFrameworkTabs>
+
+Now, you should have a fully interactive ecommerce example with the smallest JS bundle in the galaxy 🚀


AP style guide says "e-commerce." Shopify, WordPress and Amazon use ecommerce. ... in our Astro vs X page we say eCommerce... 🤪

I'm OK with ecommerce, and will make a note to update elsewhere. Just wanted it to be known that I checked, for the record!

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

This reverts commit 65e15d9.

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

sarah11918 · 2022-07-08T20:56:49Z

Thanks for fi-NIT-shing this off, Ben! Friday merge, FTW! 🥳

inwardmovement · 2022-07-09T06:42:54Z

Were Alpine stores considered? May we add comparison/examples with them?

yanthomasdev reviewed Jul 5, 2022

View reviewed changes

yanthomasdev added add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. site improvement Some thing that improves the website functionality - ask @delucis for help! labels Jul 6, 2022

natemoo-re approved these changes Jul 6, 2022

View reviewed changes

Comment thread src/pages/en/core-concepts/sharing-state.md Outdated

Comment thread src/pages/en/core-concepts/sharing-state.md

bholmesdev mentioned this pull request Jul 6, 2022

Update with-nanostores example to match docs walkthrough withastro/astro#3840

Merged

yanthomasdev reviewed Jul 6, 2022

View reviewed changes

Comment thread src/pages/en/core-concepts/sharing-state.md Outdated

delucis reviewed Jul 7, 2022

View reviewed changes

sarah11918 reviewed Jul 7, 2022

View reviewed changes

bholmesdev added 11 commits July 8, 2022 16:46

deps: bump to latest beta to use slots

31099ac

deps: add nanostores/preact

62c778a

wip: add sharing-state page

6c3ac80

wip: bad tab view

bb415f9

wip: move tab idea to bad-tabs bc it STINKS!

12612b6

feat: implement super cool slot-based tabview

a011e4e

feat: add store sharing!

17d7df9

refactor: make UIFrameworkTabs wrapper

613d66f

refactor: change prop name to sharedStore

615934a

refactor: use "ui-frameworks" sharedStore ke

0a409b4

new: preamble, "why nanostores"

e60dca7

bholmesdev and others added 25 commits July 8, 2022 16:46

edit: add links to full example repo

f69c8e9

edit: add callout on solid signals

4f3840b

nit: can use -> use

be215e3

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

fix: choppy autoscroll on safari

1c5feec

deps: bump to latest astro beta

388da23

edit: reshuffle nav placements

df007f7

Revert "edit: reshuffle nav placements"

79c9d7f

This reverts commit 65e15d9.

edit: bump sharing state to end of guides

aa6c380

fix: add unique id to each tab view

d4e066a

fix: fancy focus ring for tabs

dcf65a1

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

nit: combine comparisons into single note

4fa6b35

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

nit: add "comparisons" header to svelte and solid block

d2cd012

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

nit: remove emoji punctuation because WeRe PrOfEsSiOnAlS

eed0635

if you're reading this it's too late (to follow me @bholmesdev)

bb1055b

refactor: use JavaScript and TypeScript panels

5259c19

refactor: inherit tab group styles from getting started

c917849

nit: remove "typical" from preamble

54416c1

Update src/pages/en/core-concepts/sharing-state.md

8bd0006

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

Update src/pages/en/core-concepts/sharing-state.md

0373077

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

Update src/pages/en/core-concepts/sharing-state.md

4566386

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

Update src/pages/en/core-concepts/sharing-state.md

f820e4a

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: use "Nano Stores" instead of "nanostores"

5e6b2df

nit: should be -> will be seamless

068e6d5

nit: we may -> we can

48e1cc4

nit: You'll need... -> Astro recommends

e175c1b

bholmesdev force-pushed the new/sharing-state branch from 8061f18 to e175c1b Compare July 8, 2022 20:46

bholmesdev merged commit 6916c3c into main Jul 8, 2022

bholmesdev deleted the new/sharing-state branch July 8, 2022 20:55


		"Typical" UI frameworks like React, Vue, or Svelte may encourage ["context" providers](https://reactjs.org/docs/context.html) for other components to consume. But when [partially hydrating components](/en/core-concepts/framework-components/#hydrating-interactive-components) within Astro or Markdown, you cannot use these context wrappers 😳

		We'll need a different solution to create shared stores your components can read and write from: [nanostores](https://github.com/nanostores/nanostores).

Uh oh!

Conversation

bholmesdev commented Jul 5, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What kind of changes does this PR include?

Description

Uh oh!

netlify Bot commented Jul 5, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

crutchcorn commented Jul 5, 2022

Uh oh!

yanthomasdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zadeviggers commented Jul 6, 2022

Uh oh!

natemoo-re left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bholmesdev commented Jul 6, 2022

Uh oh!

bholmesdev commented Jul 6, 2022

Uh oh!

bholmesdev commented Jul 6, 2022

Uh oh!

zadeviggers commented Jul 6, 2022

Uh oh!

sarah11918 commented Jul 6, 2022

Uh oh!

Uh oh!

hippotastic commented Jul 6, 2022

Uh oh!

hippotastic commented Jul 7, 2022

Uh oh!

FredKSchott commented Jul 7, 2022

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 Jul 7, 2022

Choose a reason for hiding this comment

Uh oh!

bholmesdev Jul 8, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 Jul 7, 2022

Choose a reason for hiding this comment

Uh oh!

sarah11918 commented Jul 8, 2022

Uh oh!

inwardmovement commented Jul 9, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

bholmesdev commented Jul 5, 2022 •

edited

Loading

netlify Bot commented Jul 5, 2022 •

edited

Loading

inwardmovement commented Jul 9, 2022 •

edited

Loading