style: improve scroll bar styling and add yellow text element

- Improved the styling of the scroll bar in the PixiJSContainer component to have a higher z-index.
- Added a new yellow text element (YellowText) in main.ts to easily create PixiJS Text objects with yellow fill.
- Removed unnecessary imports from index.ts and moved them to main.ts.

docs/.vitepress/theme/components/PixiJSContainer/index.vue

@@ -1,7 +1,8 @@
 <script lang="ts" setup>
 import { computed, ref } from 'vue'
-import { useMessage } from 'naive-ui'
+import { NScrollbar, darkTheme, useMessage } from 'naive-ui'
 import { Application } from 'vue3-pixi'
+
 import Card from '../Card/index.vue'
 import { getCodeSandboxParams, getWithAppCodeSandboxParams } from './utils'
 
@@ -15,10 +16,12 @@ const props = withDefaults(
     metadata: Record<string, any>
     expand?: boolean
     app?: boolean
+    codesandbox?: boolean
   }>(),
   {
     expand: true,
     app: true,
+    codesandbox: true,
   },
 )
 const message = useMessage()
@@ -59,7 +62,7 @@ async function onCopyCode() {
         <div class="cursor-pointer i-akar-icons-javascript-fill p-10px" :class="[!isUsingTs && 'text-amber']" @click="isUsingTs = false" />
       </div>
       <div class="flex gap-2">
-        <form action="https://codesandbox.io/api/v1/sandboxes/define" method="POST" target="_blank" style="display: flex; padding: 0">
+        <form v-if="codesandbox" action="https://codesandbox.io/api/v1/sandboxes/define" method="POST" target="_blank" style="display: flex; padding: 0">
           <input type="hidden" name="parameters" :value="sandboxParams">
           <input type="hidden" name="query" value="file=/src/Demo.vue">
           <button
@@ -91,7 +94,15 @@ async function onCopyCode() {
       </div>
     </div>
     <template v-if="showHighlighted" #footer>
-      <div class="language-vue p0 m0!" v-html="highlightedHtml" />
+      <NScrollbar
+        style="max-height: 500px"
+        :theme-overrides="{
+          color: 'rgba(255, 255, 255, 0.6)',
+          colorHover: ' rgba(255, 255, 255, 0.3)',
+        }"
+      >
+        <div class="language-vue p0 m0!" v-html="highlightedHtml" />
+      </NScrollbar>
     </template>
   </Card>
 </template>

docs/.vitepress/theme/index.ts

@@ -6,12 +6,8 @@ import { NMessageProvider } from 'naive-ui'
 import PixiJSContainer from './components/PixiJSContainer/index.vue'
 import StackBlitzEmbed from './components/StackBlitzEmbed/index.vue'
 
-import 'floating-vue/dist/style.css'
-import 'uno.css'
-import './style.css'
+import './main'
 
-FloatingVue.options.distance = 28
-FloatingVue.options.themes.tooltip.delay.show = 100
 export default {
   ...Theme,
   Layout: () => {

docs/.vitepress/theme/main.ts

@@ -0,0 +1,23 @@
+import FloatingVue from 'floating-vue'
+import { renderer } from 'vue3-pixi'
+import { Text } from 'pixi.js'
+
+import 'floating-vue/dist/style.css'
+import 'uno.css'
+import './style.css'
+
+class YellowText extends Text {
+  constructor(text, style) {
+    super(text, style)
+    this.style.fill = 'yellow'
+  }
+}
+
+const elements = {
+  YellowText: props => new YellowText(props.text, props.style),
+}
+
+renderer.use({ elements })
+
+FloatingVue.options.distance = 28
+FloatingVue.options.themes.tooltip.delay.show = 100

docs/.vitepress/theme/style.css

@@ -111,3 +111,7 @@
 .v-popper__inner {
   padding: 4px 8px !important;
 }
+
+.n-scrollbar-rail.n-scrollbar-rail--vertical {
+  z-index: 300
+}

docs/guide/demo/custom-instance.vue

@@ -0,0 +1,3 @@
+<template>
+  <yellow-text text="Hello World" :anchor="0.5" :x="120" :y="120" />
+</template>

docs/guide/demo/loader.vue

@@ -1,4 +1,4 @@
-<script lang="ts" setup>
+<script setup>
 import { Application, Loader } from 'vue3-pixi'
 
 const images = [
@@ -24,9 +24,9 @@ const images = [
           v-for="(image, k, i) in textures" :key="k"
           :texture="image"
           :anchor="0.5"
-          :x="70 + i * 50"
+          :x="68 + i * 50"
           :y="120"
-          :scale="2"
+          :scale="1.4"
         />
       </template>
     </Loader>

docs/guide/demo/refs.vue

@@ -0,0 +1,15 @@
+<script lang="ts" setup>
+import { onMounted, ref } from 'vue'
+import type { TextInst } from 'vue3-pixi'
+
+const textRef = ref<TextInst>()
+onMounted(() => {
+  textRef.value!.style.fill = 'yellow'
+})
+</script>
+
+<template>
+  <text ref="textRef" :anchor="0.5" :x="120" :y="120">
+    Hello World
+  </text>
+</template>

docs/guide/demo/sprite.vue

@@ -4,6 +4,11 @@ import { Application } from 'vue3-pixi'
 
 <template>
   <Application :width="240" :height="240">
-    <sprite texture="/assets/food/lemonpie.png" />
+    <sprite
+      texture="/assets/food/lemonpie.png"
+      :anchor="0.5"
+      :x="120"
+      :y="120"
+    />
   </Application>
 </template>

docs/guide/demo/ticker.vue

@@ -0,0 +1,22 @@
+<script lang=ts setup>
+import { reactive } from 'vue'
+import { onTick } from 'vue3-pixi'
+
+const position = reactive({ x: 120, y: 120 })
+
+let count = 0
+onTick((delta) => {
+  count += delta * 0.05
+  position.x = 120 + Math.cos(count) * 50
+  position.y = 120 + Math.sin(count) * 50
+})
+</script>
+
+<template>
+  <sprite
+    texture="/assets/food/lemonpie.png"
+    :position="position"
+    :anchor="0.5"
+    :scale="1.4"
+  />
+</template>

docs/guide/usage.md

@@ -1,6 +1,6 @@
 # Usage
 
-The Application component will create your PixiJS app and canvas for you.
+The [Application](/) component will create your PixiJS app and canvas for you.
 
 All Vue3 Pixi elements should be children of Application.
 
@@ -22,4 +22,73 @@ If you have a bunch of images or other resources, you may wish to show a loading
 
 > Note: You may want to enable network throttling in your browser dev tools to actually see the loading screen - these are small images!
 
-<demo src="./demo/loader.vue" :app="false" />
+<demo src="./demo/loader.vue" :app="false" />
+
+You can have multiple Loader components as well, which could be useful if you wanted to render a fallbacks at a component-level instead.
+
+## Ticker
+
+A [Ticker](/) runs an update loop for the `application`. The Application component will create one automatically, which means child components can hook into the loop with `onTick`.
+
+<demo src="./demo/ticker.vue" />
+
+## Accessing PixiJS Instances
+
+You can bind PixiJS instances through ref, It is like the HTML elements, so you can bind to it if you need to access it.
+
+<demo src="./demo/refs.vue" />
+
+## Using a Custom Instance
+
+You can add custom `PIXI` instances to the `renderer`, if you have a custom class (whether that be your own or from a third-party library).
+
+```ts
+// main.js
+import { Text } from 'pixi.js'
+import { renderer } from 'vue3-pixi'
+
+class YellowText extends Text {
+  constructor(text, style) {
+    super(text, style)
+    this.style.fill = 'yellow'
+  }
+}
+
+const elements = {
+  YellowText: props => new YellowText(props.text, props.style),
+}
+
+function pathProp(el, key, prevValue, nextValue) {
+  if (el instanceof YellowText) {
+    // handle special prop here and return true.
+  }
+}
+
+renderer.use({ elements, pathProp })
+
+// ...
+```
+
+<demo src="./demo/custom-instance.vue" :codesandbox="false" />
+
+If you are using TypeScript, you can also declare your custom instance using `declare module '@vue/runtime-core'`.
+
+```ts
+import type { TextProps } from 'vue3-pixi'
+
+interface YellowTextProps extends TextProps {
+  text: string
+  style: TextStyle
+  // ...
+}
+
+interface YellowTextComponent {
+  (props: YellowTextProps): any
+}
+
+declare module '@vue/runtime-core' {
+  interface GlobalComponents {
+    YellowText: YellowTextComponent
+  }
+}
+```

packages/renderer/src/renderer/index.ts

@@ -1,19 +1,29 @@
-import type { Container } from 'pixi.js'
+import type { Container, DisplayObject } from 'pixi.js'
 
+import type { Renderer as _Renderer } from 'vue-demi'
 import { createRenderer as _createRenderer } from 'vue-demi'
-import { isCustomElement } from '../compiler'
 
-import { patchProp } from './patchProp'
+import { isCustomElement } from '../compiler'
+import { patchProp, patchProps } from './patchProp'
 import { nodeOps as _nodeOps } from './nodeOps'
-
-const { createElement, setText, ...nodeOps } = _nodeOps
-const { createApp: _createApp, render: _render } = createRenderer()
+import type { CustomElement } from './ops'
+import { elements } from './ops'
 
 export interface RendererOptions {
   prefix?: string
 }
 
-export function createRenderer(options: RendererOptions = {}) {
+export interface CustomRendererOptions {
+  elements: Record<string, CustomElement>
+  pathProp?: (el: any, key: string, prevValue: any, nextValue: any) => boolean | void
+}
+export interface Renderer<T = Container<DisplayObject>> extends _Renderer<T> {
+  use: (options: CustomRendererOptions) => void
+}
+
+const { createElement, setText, ...nodeOps } = _nodeOps
+
+function createRenderer(options: RendererOptions = {}) {
   const { prefix = 'pixi' } = options
   const renderer = _createRenderer<Container, Container>({
     createElement: (name, _, __, props) => createElement(prefix, name, props),
@@ -25,14 +35,31 @@ export function createRenderer(options: RendererOptions = {}) {
   return renderer
 }
 
-export const createApp: typeof _createApp = (...args: any[]) => {
+const renderer = createRenderer() as Renderer
+
+const _createApp = renderer.createApp
+const _render = renderer.render
+function $createApp(...args: any[]) {
   const app = (_createApp as any)(...args)
-  Object.assign(app.config.compilerOptions, { isCustomElement })
+  Object.assign(app.config.compilerOptions, {
+    isCustomElement,
+  })
   return app
 }
-export const render: typeof _render = (...args: any[]) => {
-  return (render as any)(...args)
+function $render(...args: any[]) {
+  return (_render as any)(...args)
+}
+function $use(options: CustomRendererOptions) {
+  Object.assign(elements, options.elements)
+  options.pathProp && patchProps.push(options.pathProp)
 }
+Object.assign(renderer, {
+  createApp: $createApp,
+  render: $render,
+  use: $use,
+})
 
+export const createApp = renderer.createApp
+export const render = renderer.render
+export { renderer, createRenderer }
 export * from './setter'
-export * from './use'

packages/renderer/src/renderer/nodeOps.ts

@@ -56,6 +56,7 @@ export function nextSibling(node: Container) {
 
 export function setText(prefix: string, node: Container, text: string) {
   text = text.replace(/\\n/g, '\n')
+
   node instanceof Text || node instanceof BitmapText
     ? node.text = text.trim()
     : warn(`Text is only supported with ${prefix}-text element`)