From 8ff599c0f2b329d13b40f1256ae2ead5c1c1691a Mon Sep 17 00:00:00 2001
From: Marek Piasecki <mad@maniak.pro>
Date: Wed, 18 Jan 2023 19:10:14 +0100
Subject: [PATCH] finish usage description

---
 src/main.imba        |  14 ++++-
 src/views.json       |   2 +-
 src/views/usage.imba | 130 ++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 141 insertions(+), 5 deletions(-)

diff --git a/src/main.imba b/src/main.imba
index 2db5eba..833b577 100644
--- a/src/main.imba
+++ b/src/main.imba
@@ -6,7 +6,7 @@ global css
 	.activated bgc:violet3
 	.disabled, .disabled@hover filter:grayscale(100%)
 	.zoomed scale:1.05
-	.button d:inline-block m:2px bgc:none c:violet7 td:none bxs:sm us:none
+	.button d:inline-block m:2px bgc:none c:violet7 td:none bxs:sm us:none cursor:pointer
 	.button@hover, .button.active bxs:md filter:hue-rotate(5deg) mb:0px pt:12px td:none
 	.button, code, .bordered p:10px bd:2px solid violet5 rd:10px d:inline-block
 	.bordered p:2.5px bw:1.5px c:violet9
@@ -56,11 +56,17 @@ tag imba-code < pre
 		<code.url><.url> url if url
 		<slot name='live'>
 		<code.content><slot>
+tag code-inline < imba-code
+	css
+		d:inline
+		code d:inline-block
 
 tag c-el
 	css d:inline c:gray3
 tag c-op < c-el
 	css c:white fw:bold
+tag c-fl < c-el
+	css c:purple5
 tag c-c < c-el
 	css c:blue3
 tag c-com < c-el
@@ -82,6 +88,10 @@ tag c-tag-def < c-el
 	<self[c:blue4]>
 		"tag "
 		<[c:green5 d:inline]><slot>
+tag c-let < c-el
+	<self[c:blue4]>
+		"let "
+		<c-el><slot>
 
 tag pro-tip
 	<self[bgc:gray0 p:15px]>
@@ -92,7 +102,7 @@ import './views/home.imba'
 import './views/installation.imba'
 import './views/usage.imba'
 
-tag view-examples
+tag view-use-cases
 	<self> "Examples:"
 
 tag view-why-to-use-it
diff --git a/src/views.json b/src/views.json
index 4af5974..3d0d18e 100644
--- a/src/views.json
+++ b/src/views.json
@@ -1 +1 @@
-["home","examples","why-to-use-it","installation","usage"]
\ No newline at end of file
+["home","use-cases","why-to-use-it","installation","usage"]
\ No newline at end of file
diff --git a/src/views/usage.imba b/src/views/usage.imba
index a9ee512..de4d474 100644
--- a/src/views/usage.imba
+++ b/src/views/usage.imba
@@ -3,6 +3,12 @@ tag view-usage
 		"This integration provides "
 		<b> 3
 		" components:"
+		<b> "ref"
+		", "
+		<b> "toggle"
+		" and "
+		<b> "router"
+		"."
 		<br>
 		<br>
 		<.bordered> "<pro-ref>"
@@ -98,12 +104,12 @@ tag view-usage
 			"""
 		<br>
 		"A bit more complex example:"
-		<imba-code url="/{R.param('subview')}">
+		<imba-code url="/{R.params.subview || ''}">
 			"""
 			{<c-tag-def> 'my-app'}
 			    {<c-tag> 'self'}
 			        {<c-tag> "pro-ref-f{<c-el> ' view'}{<c-op> '='}{<c-el> 'v'}"} {<c-op> 'for'} v {<c-op> 'in'} {<c-c> 'R'}{<c-op> '.'}views {<c-com> 'render menu'} 
-			        {<c-tag> "pro-router"}                      {<c-com> 'slot for current view'}
+			        {<c-tag> "pro-router"}                        {<c-com> 'slot for current view'}
 
 			{<c-tag-def> 'view-hello'}
 			    {<c-tag> 'self'} 'Hello World!'
@@ -123,7 +129,127 @@ tag view-usage
 				<c-tag> "pro-router{<c-el> ' view'}{<c-op> '='}{<c-c> 'R'}{<c-op> '.'}param{<.c-br> '('}{<c-str> 'subview'}{<.c-br> ')'}"
 
 		<br>
+		<h2.gradient> "Pro-router tips"
+		"Further reading is not about functionalities provided by this package itself but the ones you will be using straight from pro-router."
+		<br>
+		<br>
+		<.example>
+			<code-inline> "{<c-c> 'R'}{<c-op> '.'}param{<.c-br> '('}{<c-str> 'key'}{<.c-br> ')'}"
+			<p>
+				"Use it to receive param value for given { <i> 'key' }."
+				<br>
+				"Value will be automatically processed with key { <b> 'getter' } if provided."
+				<br>
+				"It's awesome because you immidietaly work on a real object."
+		<br>
+		<pro-tip>
+			<.example>
+				<code-inline> "{<c-c> 'R'}{<c-op> '.'}params{<c-op> '.'}key"
+				<p> "You can ommit getter by going straight for the parameter."
+		<br>
+		<br>
+		<.example>
+			<code-inline> "{<c-c> 'R'}{<c-op> '.'}write{<.c-br> '('}{<c-str> 'key'}{<c-op> ','} value{<.c-br> ')'}"
+			<p>
+				"Use it to store the { <i> 'value' } under given param { <i> 'key' }."
+				<br>
+				"Value will be automatically processed with key { <b> 'setter' } if provided."
+				<br>
+				"It's awesome because you can easily store anything in a nice format this way."
+		<pro-tip>
+			"Writing doesn't change browser history. This way you can bind directly user input to url."
+			<imba-code url="/{("user-input/" + R.params['user-input'] if R.params['user-input']) || ''}">
+				<c-tag> "input{<c-c> '$v'} type{<c-op> '='}{<c-str> 'text'} value{<c-op> '='}{<c-c> 'R'}{<c-op> '.'}param{<.c-br> '('}{<c-str> 'user-input'}{<.c-br> ')'} {<c-op> '@keyup='}{<c-c> 'R'}{<c-op> '.'}write{<.c-br> '('}{<c-str> 'user-input'}{<c-op> ', '}{<c-c> '$v'}{<c-op> '.'}value{<.c-br> ')'}"
+				<div[d:vcc h:100px] slot="live">
+					<input$v type='text' value=R.param('user-input') @keyup=R.write('user-input', $v.value)>
+		<h3.gradient> "Using getters and setters"
+		"This is very simple yet powerful feature which can fullfil many different functions."
+		<br>
+		<br>
+		<b> "Format a nice url:"
+		<imba-code url="/{("title/" + R.params.title if R.params.title) || ''}">
+			"{<c-c> 'R'}{<c-op> '.'}setters{<c-op> '.'}title {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}{<c-c> 'v' }{<c-op> '|'} v{<c-op> '.'}replaceAll{<.c-br> '('}{<c-str> ' '}{<c-op> ', '}{<c-str> '-'}{<.c-br> ')'}"
+			<br>
+			"{<c-c> 'R'}{<c-op> '.'}getters{<c-op> '.'}title {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}{<c-c> 'v' }{<c-op> '|'} v{<c-op> '.'}replaceAll{<.c-br> '('}{<c-str> '-'}{<c-op> ', '}{<c-str> ' '}{<.c-br> ')'}"
+
+			<div[d:vcc h:100px] slot="live">
+				<label> "Title: {R.param('title')}"
+				<input$v2 type='text' value=R.param('title') @keyup=R.write('title', $v2.value)>
+		<br>
+		<br>
+		<b> "Set default value:"
+		<imba-code url="/{("name/" + R.params.name if R.params.name) || ''}">
+			"{<c-c> 'R'}{<c-op> '.'}setters{<c-op> '.'}name {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}{<c-c> 'v' }{<c-op> '|'} v {<c-fl> 'if '}{<c-str> 'Johny'}{<c-op> '!='} v"
+			<br>
+			"{<c-c> 'R'}{<c-op> '.'}getters{<c-op> '.'}name {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}{<c-c> 'v' }{<c-op> '|'} v {<c-op> '||'} {<c-str> 'Johny'}"
+
+			<div[d:vcc h:100px] slot="live">
+				<label> "Hello {R.param('name')}!"
+				<input$v3 type='text' value=(R.params.name ? R.param('name') : '') @keyup=R.write('name', $v3.value)>
 		<br>
+		<br>
+		<b> "Give you right away a proper object:"
+		<imba-code url="/{("number/" + R.params.number if R.params.number) || ''}{("/cucumber/" + R.params.cucumber if R.params.cucumber) || ''}">
+			"{<c-c> 'R'}{<c-op> '.'}getters{<c-op> '.'}number {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}{<c-c> 'v' }{<c-op> '|'} {<c-c> 'Number'}{<.c-br> '('}v{<.c-br> ')'}"
+
+			<div[d:vcc h:150px] slot="live">
+				<[d:inline-block]>
+					<.button@click=(R.write 'number', R.param('number') - 1)> "-"
+					" With getter: {R.param('number')} "
+					<.button@click=(R.write 'number', R.param('number') + 1)> "+"
+				<br>
+				<[d:inlne-block]>
+					<.button@click=(R.write 'cucumber', R.param('cucumber') - 1)> "-"
+					" Without getter: {R.param('cucumber')} "
+					<.button@click=(R.write 'cucumber', R.param('cucumber') + 1)> "+"
+		<br>
+		<br>
+		<b> "Validates value:"
+		<imba-code url="/{("one2four/" + R.params.one2four if R.params.one2four) || ''}">
+			"""
+			{<c-tag-def> "valid{<.c-br> '('}{<c-el> 'v'}{<.c-br> ')'}"}
+			    {<c-c> 0} {<c-op> '<'} v {<c-op> 'and'} v {<c-op> '<'} {<c-c> 4}
+
+			{<c-c> 'R'}{<c-op> '.'}setters{<c-op> '.'}one2four {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}v{<c-op> '|'} valid{<.c-br> '('}v{<.c-br> ')'} {<c-fl> '?'} v {<c-fl> ':'} {<c-c> 'R'}{<c-op> '.'}params{<c-op> '.'}one2four
+			{<c-c> 'R'}{<c-op> '.'}getters{<c-op> '.'}one2four {<c-op> '='} {<c-fl> 'do'} {<c-op> '|'}v{<c-op> '|'}
+			    {<c-fl> 'if'} v
+			        {<c-let> 'number'} {<c-op> '='} {<c-c> 'Number'}{<.c-br> '('}v{<.c-br> ')'}
+			        {<c-fl> 'return'} number {<c-fl> 'if'} valid{<.c-br> '('}number{<.c-br> ')'}
+			    {<c-c> 1}
+			"""
+
+			<div[d:vcc h:100px] slot="live">
+				<[d:inline-block]>
+					<.button@click=(R.write 'one2four', R.param('one2four') - 1)> "-"
+					<b> " {R.param('one2four')} "
+					<.button@click=(R.write 'one2four', R.param('one2four') + 1)> "+"
+		
+		<br>
+		<a.button href='#/usage/'> "Reset playground"
+		<br>
+		<br>
+		<br>
+		"Complementary read: "
+		<a href="http://router.maniak.pro/#/docs"> 'router.maniak.pro/#/docs'
+
+R.setters.title = do |v| v.replaceAll(' ', '-')
+R.getters.title = do |v| v.replaceAll('-', ' ')
+R.setters.name = do |v| v if "Johny" != v
+R.getters.name = do |v| v || "Johny"
+R.getters.number = do |v| Number(v)
+
+def valid(v)
+	0 < v and v < 4
+
+R.setters.one2four = do |v| valid(v) ? v : R.params.one2four
+R.getters.one2four = do |v|
+	if v
+		let number = Number(v)
+		return number if valid(number)
+	1
+css .example
+	d:htl
+	> mr: 10px
 
 tag example-menu
 	<self>