Merge pull request #616 from thejackshelton/website-contributing

Website contributing

Author: thejackshelton

apps/website/public/images/contributing/code-cave.webp

@@ -18,4 +18,8 @@
   ol li {
     @apply my-4;
   }
+
+  img {
+    @apply my-4 block rounded-lg md:my-8;
+  }
 }

apps/website/public/images/contributing/packages.webp

@@ -0,0 +1,241 @@
+---
+title: 'Qwik UI - Contributing'
+---
+
+import { Note } from '~/components/note/note';
+import { APITable } from '~/components/api-table/api-table';
+import { FeatureList } from '~/components/feature-list/feature-list';
+import { StatusBanner } from '~/components/status-banner/status-banner';
+import { InfoPopup } from '~/components/info-popup/info-popup';
+import { statusByComponent } from '~/_state/component-statuses';
+
+# Contributing
+
+Thinking about contributing to the project, but don't know where to start? You're in the right place!
+
+We'll get you up in shape in no time, and ready to hop into the Qwik UI code cave.
+
+![The Qwik UI Code Cave](/images/contributing/code-cave.webp)
+
+## There are **two projects** we currently work on:
+
+### Qwik UI Headless
+
+Don't know what a headless library is? [This might help](https://www.smashingmagazine.com/2022/05/you-dont-need-ui-framework/).
+
+### Fluffy.
+
+A styled copy paste library with TailwindCSS inspired by [Shadcn](https://ui.shadcn.com/docs).
+
+## There's a lot of stuff here!
+
+Yep, `99%` of the time you're gonna be in two directories:
+
+**website** - `apps/website`
+
+**packages** - `packages/kit-headless` or `packages/kit-fluffy`
+
+<div class="flex max-w-full flex-col gap-4 xl:flex-row">
+  <img
+    class="block max-w-[400px] object-contain"
+    src="/images/contributing/website.webp"
+  />
+  <img
+    class="block max-w-[300px] object-contain"
+    src="/images/contributing/packages.webp"
+  />
+</div>
+
+## **Which component should I work on?**
+
+Feel free to work on anything that doesn't have a `stable` tag on it! The components with the most priority have the `planned` or `draft` tags beside them.
+
+> Is something not covered in the library that you think should be? Make an issue and the project maintainers can give the go-ahead on its development.
+
+## Headless
+
+Check out the [introduction section](https://qwikui.com/docs/headless/introduction/) to see the principles of Qwik UI, and the project goals. As a heads up, those may change over time with more discussion!
+
+### I don't know anything about accessibility, can I still contribute?
+
+Of course! Neither did we before starting this project. Our go-to resource is the [Aria Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/). Find the component you're going for, and read through the component guide.
+
+<Note status="warning">
+  **Disclaimer**: following the guide does not necessarily mean it's accessible, you can
+  think of it as a starting guide that'll get you 70% there. The only way to truly test is
+  with assistive technology, such as a **screenreader**.
+</Note>
+
+We also have plenty of other [accessibility resources](https://discord.com/channels/990511757091033108/1114309494986506401/1114309494986506401) you can skim through. Feel free to ask questions!
+
+## When is a headless component beta?
+
+### It has features
+
+It can be used for most common use cases, and maybe some advanced ones (if you'd like to go further).
+
+What I like to do is look at other places around the web and see how things work! What kind of features do they have? Does someone already have a need for this in the Qwik community? How would I go about approaching this?
+
+We also take inspiration from awesome headless libraries in other communities. For example, like the popular headless libraries below:
+
+- [Radix UI](https://www.radix-ui.com/primitives/docs/components/accordion) is a React Headless library.
+- [React Aria](https://react-spectrum.adobe.com/react-aria/components.html) is a React Headless library.
+- [Melt UI](https://melt-ui.com/docs/builders/accordion) is a Svelte headless library.
+- [Kobalte](https://kobalte.dev/docs/core/components/accordion) is a Solid JS headless library
+- [Headless UI](https://headlessui.com/) is a React and Vue headless library.
+- [Ark UI](https://ark-ui.com/) is a headless library that uses state machines.
+- [React Headless Hooks](https://webeetle.github.io/react-headless-hooks/docs/useAccordion) is a hooks based headless library for React.
+- [Downshift](https://www.downshift-js.com/) is a hooks based library for accessible comboboxes and select components.
+
+I love going through these projects and understanding the why and what problems they solve. What kinda features do all of them have in common? How do they name things? What conventions do they use? How satisfied are people consuming it?
+
+I think this is a good way to figure out what to work on. That said, we also want to keep things simple, and not add features unless we know there is a demand for them (hence looking for similarities).
+
+> Ideally, we would like the surface API to be simple, but **powerful**. Post 1.0, we are also looking to refactor the components to use hook logic under the hood, and provide a hooks API to keep things as customizable as possible, giving the opportunity to use a hook or a component!
+
+## Tests
+
+Tests ensure we can sleep sound at night and know that our component behavior is working as intended. Part of the Qwik core team, Shai Reznik (and also a contributor here!) talks a lot about [test driven development](https://www.youtube.com/watch?v=KHaeVaSkhIE).
+
+### TDD Process
+
+- we need a new feature!
+- make a failing test with the desired behavior (wut?)
+- get the test passing by adding said feature!
+- enjoy life when refactoring 🏝️
+
+We currently use [playwright](https://playwright.dev/docs/intro) for testing.
+
+> We also currently have a few cypress tests that we are migrating over to playwright.
+
+Shai also has a testing course that Qwik UI contributors get access to for the price of **FREE**! Don't hesitate to reach out.
+
+## Docs
+
+We use [MDX](https://mdxjs.com/docs/what-is-mdx/) for interactive markdown.
+
+You can find the headless docs [here](https://github.com/qwikifiers/qwik-ui/tree/main/apps/website/src/routes/docs/headless).
+
+When creating the docs, we have a `showcase` component, which gives typescript support, a component preview of your example, and **automatically** updates the code example as you edit it! 🤯
+
+> Here's [an example](https://github.com/qwikifiers/qwik-ui/blob/main/apps/website/src/routes/docs/headless/modal/examples/main.tsx) of someone consuming a headless component! In `index.mdx` we can use `<Showcase name="main" />`, because `main.tsx` is the file path.
+
+The same thing goes for our `snippet` component, which is for showing code blocks only.
+
+### Docs Components
+
+We also have more [docs components](https://github.com/qwikifiers/qwik-ui/tree/main/apps/website/src/components) to make your life easier! Some examples being:
+
+### Notes
+
+<Note>I am a note component!</Note>
+
+### API table
+
+<APITable
+  propDescriptors={[
+    {
+      name: 'behavior',
+      type: 'string',
+      description:
+        'Determines whether the Accordion will open one or multiple items at a time.',
+    },
+    {
+      name: 'onSelectedIndexChange$',
+      type: 'function',
+      info: 'PropFunction<(index: number) => void>',
+      description:
+        'An event hook that gets notified whenever the selected index changes.',
+    },
+    {
+      name: 'onFocusIndexChange$',
+      type: 'function',
+      info: 'PropFunction<(index: number) => void>',
+      description: 'An event hook that gets notified whenever the focus index changes.',
+    },
+  ]}
+/>
+
+### Feature list
+
+<FeatureList features={['feature A', 'feature B']} />
+
+### Component status banner
+
+<StatusBanner status={statusByComponent.headless.Collapsible} />
+
+### info popup (uses the popover)
+
+<InfoPopup info="Some info!" />
+
+### **What if I only want to do docs contributions, is that ok?**
+
+Absolutely, documentation is a critical part of the project, and something that can be very much improved! I recommend checking out [Sarah Rainsberg's Docs Guide](https://contribute.docs.astro.build/welcome/), it's partly towards Astro, but is also a great general resource for writing good documentation.
+
+## Where should I learn the Qwik parts?
+
+If you find yourself stuck on a certain pattern, try taking a look through Qwik UI beta components. For example, the [modal component](https://github.com/qwikifiers/qwik-ui/tree/main/packages/kit-headless/src/components/modal) would be a good one to look through.
+
+We're also happy to help! We love experimenting with things and having a blast while doing it.
+
+### What's something I should avoid?
+
+[useVisibleTask$](https://qwik.dev/docs/guides/best-practices/#use-usevisibletask-as-a-last-resort). It's an escape hatch, and for 95% of UI components I can promise you that it's not needed.
+
+You're pretty much saying "hey Qwik! All those benefits you do to lazy load and delay the execution of code? Let's throw those away".
+
+Instead, look at it this way:
+
+Where does my user interact with things? And how can I make sure that we can _delay_ the execution of that code until the user ABSOLUTELY needs it.
+
+Here's a code example I've seen in the Qwik discord. The developer is trying to make sure that an open menu navbar is closed when the window is resized over `1248px`
+
+```tsx
+useVisibleTask$(({ cleanup }) => {
+  const updateDocumentClass = () => {
+    if (menuOpen.value && window.innerWidth > 1248) {
+      menuOpen.value = false;
+      document.documentElement.classList.remove('modal-open');
+    }
+  };
+
+  window.addEventListener('resize', updateDocumentClass);
+
+  cleanup(() => {
+    window.removeEventListener('resize', updateDocumentClass);
+  });
+});
+```
+
+Because this code is directly tied to an event, we should not be using a visible task. We could achieve the same result with:
+
+```tsx
+useOnWindow('resize', $(() => {
+  if (menuOpen.value && window.innerWidth > 1248) {
+    menuOpen.value = false;
+    document.documentElement.classList.remove('modal-open');
+  }
+});
+```
+
+We promise that creating ui elements gets easier once you have a clear mental model for API's like `useTask$`. Here are some alternatives to explore.
+
+- [Events](https://qwik.dev/docs/components/events/#events) - onClick$, onScroll$, onKeydown$
+- [useTask$](https://qwik.dev/docs/components/tasks/#usetask) - (running code initially on server, tracked change on client)
+- [useComputed$](https://qwik.dev/docs/components/state/#usecomputed) - deriving state synchronously
+- [Custom Events](https://github.com/thejackshelton/astro-qwik-global-state-example/blob/main/src/components/counter.tsx). Check out `random-island.tsx` too.
+- [sync$](https://qwik.dev/docs/cookbook/sync-events/#sync-synchronous-events-beta) - perform some browser work
+  ex: preventDefault w/ onKeyDown$, localStorage
+- [useVisibleTask$](https://qwik.dev/docs/components/tasks/#usevisibletask) (the last resort)
+
+We want to squeeze as much possible performance out of Qwik, and stay with the principle that things execute on interaction. This allows consumers to have a fast app without even trying!
+
+## How do I make a PR?
+
+We cover it in-depth in the [contributing guide](https://github.com/qwikifiers/qwik-ui/blob/main/CONTRIBUTING.md) here.
+
+## That's it!
+
+Hopefully you should have enough to get up and running with Qwik UI Headless, if you have any questions don't let us stop you from reaching out, and happy building :qwik:
+
+If you'd like to work on the styled library that's entirely a possibility too, there's currently documentation on the headless is all.